commit 7f91dc11640ecc725984c72acfe4a261096826a5 Author: Raatty Date: Thu Apr 23 21:49:16 2020 +1200 basic lightdm bindings made diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..eb5a316 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +target diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..d208b3a --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,358 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +[[package]] +name = "anyhow" +version = "1.0.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d9a60d744a80c30fcb657dfe2c1b22bcb3e814c1a1e3674f32bf5820b570fbff" + +[[package]] +name = "bitflags" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf1de2fe8c75bc145a2f577add951f8134889b4795d47466a54a5c846d691693" + +[[package]] +name = "either" +version = "1.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb1f6b1ce1c140482ea30ddd3335fc0024ac7ee112895426e0a629a6c20adfe3" + +[[package]] +name = "futures-channel" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0c77d04ce8edd9cb903932b608268b3fffec4163dc053b3b402bf47eac1f1a8" +dependencies = [ + "futures-core", +] + +[[package]] +name = "futures-core" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f25592f769825e89b92358db00d26f965761e094951ac44d3663ef25b7ac464a" + +[[package]] +name = "futures-executor" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f674f3e1bcb15b37284a90cedf55afdba482ab061c407a9c0ebbd0f3109741ba" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a638959aa96152c7a4cddf50fcb1e3fede0583b27157c26e67d6f99904090dc6" + +[[package]] +name = "futures-macro" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a5081aa3de1f7542a794a397cde100ed903b0630152d0973479018fd85423a7" +dependencies = [ + "proc-macro-hack", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "futures-task" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b0a34e53cf6cdcd0178aa573aed466b646eb3db769570841fda0c7ede375a27" + +[[package]] +name = "futures-util" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "22766cf25d64306bedf0384da004d05c9974ab104fcc4528f1236181c18004c5" +dependencies = [ + "futures-core", + "futures-macro", + "futures-task", + "pin-utils", + "proc-macro-hack", + "proc-macro-nested", + "slab", +] + +[[package]] +name = "gio" +version = "0.8.1" +source = "git+https://github.com/gtk-rs/gio#fb5777a7ab69a0a87b56ed85615adc4f46854f89" +dependencies = [ + "bitflags", + "futures-channel", + "futures-core", + "futures-io", + "futures-util", + "gio-sys", + "glib", + "glib-sys", + "gobject-sys", + "libc", + "once_cell", +] + +[[package]] +name = "gio-sys" +version = "0.9.1" +source = "git+https://github.com/gtk-rs/sys#6bd0cab694a0b446d5fe530cd87bf2b499f065ff" +dependencies = [ + "glib-sys", + "gobject-sys", + "libc", + "pkg-config", +] + +[[package]] +name = "glib" +version = "0.9.3" +source = "git+https://github.com/gtk-rs/glib#b5b4df5dc7ca52af170aafd18203bfdd42ca5608" +dependencies = [ + "bitflags", + "futures-channel", + "futures-core", + "futures-executor", + "futures-task", + "futures-util", + "glib-macros", + "glib-sys", + "gobject-sys", + "libc", + "once_cell", +] + +[[package]] +name = "glib-macros" +version = "0.9.0" +source = "git+https://github.com/gtk-rs/glib#b5b4df5dc7ca52af170aafd18203bfdd42ca5608" +dependencies = [ + "anyhow", + "heck", + "itertools", + "proc-macro-crate", + "proc-macro-error", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "glib-sys" +version = "0.9.1" +source = "git+https://github.com/gtk-rs/sys#6bd0cab694a0b446d5fe530cd87bf2b499f065ff" +dependencies = [ + "libc", + "pkg-config", +] + +[[package]] +name = "gobject-sys" +version = "0.9.1" +source = "git+https://github.com/gtk-rs/sys#6bd0cab694a0b446d5fe530cd87bf2b499f065ff" +dependencies = [ + "glib-sys", + "libc", + "pkg-config", +] + +[[package]] +name = "heck" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20564e78d53d2bb135c343b3f47714a56af2061f1c928fdb541dc7b9fdd94205" +dependencies = [ + "unicode-segmentation", +] + +[[package]] +name = "itertools" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "284f18f85651fe11e8a991b2adb42cb078325c996ed026d994719efcfca1d54b" +dependencies = [ + "either", +] + +[[package]] +name = "libc" +version = "0.2.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "99e85c08494b21a9054e7fe1374a732aeadaff3980b6990b94bfd3a70f690005" + +[[package]] +name = "light-dm-sys" +version = "0.0.1" +dependencies = [ + "gio-sys", + "glib-sys", + "gobject-sys", + "libc", + "pkg-config", +] + +[[package]] +name = "lightdm" +version = "0.1.0" +dependencies = [ + "gio", + "gio-sys", + "glib", + "glib-sys", + "gobject-sys", + "libc", + "light-dm-sys", + "once_cell", +] + +[[package]] +name = "once_cell" +version = "1.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1c601810575c99596d4afc46f78a678c80105117c379eb3650cf99b8a21ce5b" + +[[package]] +name = "pin-utils" +version = "0.1.0-alpha.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5894c618ce612a3fa23881b152b608bafb8c56cfc22f434a3ba3120b40f7b587" + +[[package]] +name = "pkg-config" +version = "0.3.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05da548ad6865900e60eaba7f589cc0783590a92e940c26953ff81ddbab2d677" + +[[package]] +name = "proc-macro-crate" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e10d4b51f154c8a7fb96fd6dad097cb74b863943ec010ac94b9fd1be8861fe1e" +dependencies = [ + "toml", +] + +[[package]] +name = "proc-macro-error" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "18f33027081eba0a6d8aba6d1b1c3a3be58cbb12106341c2d5759fcd9b5277e7" +dependencies = [ + "proc-macro-error-attr", + "proc-macro2", + "quote", + "syn", + "version_check", +] + +[[package]] +name = "proc-macro-error-attr" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a5b4b77fdb63c1eca72173d68d24501c54ab1269409f6b672c85deb18af69de" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "syn-mid", + "version_check", +] + +[[package]] +name = "proc-macro-hack" +version = "0.5.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d659fe7c6d27f25e9d80a1a094c223f5246f6a6596453e09d7229bf42750b63" + +[[package]] +name = "proc-macro-nested" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e946095f9d3ed29ec38de908c22f95d9ac008e424c7bcae54c75a79c527c694" + +[[package]] +name = "proc-macro2" +version = "1.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df246d292ff63439fea9bc8c0a270bed0e390d5ebd4db4ba15aba81111b5abe3" +dependencies = [ + "unicode-xid", +] + +[[package]] +name = "quote" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2bdc6c187c65bca4260c9011c9e3132efe4909da44726bad24cf7572ae338d7f" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "serde" +version = "1.0.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "36df6ac6412072f67cf767ebbde4133a5b2e88e76dc6187fa7104cd16f783399" + +[[package]] +name = "slab" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c111b5bd5695e56cffe5129854aa230b39c93a305372fdbb2668ca2394eea9f8" + +[[package]] +name = "syn" +version = "1.0.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0df0eb663f387145cab623dea85b09c2c5b4b0aef44e945d928e682fce71bb03" +dependencies = [ + "proc-macro2", + "quote", + "unicode-xid", +] + +[[package]] +name = "syn-mid" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7be3539f6c128a931cf19dcee741c1af532c7fd387baa739c03dd2e96479338a" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "toml" +version = "0.5.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ffc92d160b1eef40665be3a05630d003936a3bc7da7421277846c2613e92c71a" +dependencies = [ + "serde", +] + +[[package]] +name = "unicode-segmentation" +version = "1.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e83e153d1053cbb5a118eeff7fd5be06ed99153f00dbcd8ae310c5fb2b22edc0" + +[[package]] +name = "unicode-xid" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "826e7639553986605ec5979c7dd957c7895e93eabed50ab2ffa7f6128a75097c" + +[[package]] +name = "version_check" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "078775d0255232fb988e6fccf26ddc9d1ac274299aaedcedce21c6f72cc533ce" diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..5dd3d34 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,28 @@ +[package] +name = "lightdm" +version = "0.1.0" +authors = ["Raatty "] + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +libc = "0.2" +once_cell = "1.3.1" + +[dependencies.light-dm-sys] +path = "./lightdm-sys" + +[dependencies.glib] +git = "https://github.com/gtk-rs/glib" + +[dependencies.glib-sys] +git = "https://github.com/gtk-rs/sys" + +[dependencies.gobject-sys] +git = "https://github.com/gtk-rs/sys" + +[dependencies.gio] +git = "https://github.com/gtk-rs/gio" + +[dependencies.gio-sys] +git = "https://github.com/gtk-rs/sys" diff --git a/Gir.toml b/Gir.toml new file mode 100644 index 0000000..95e58d0 --- /dev/null +++ b/Gir.toml @@ -0,0 +1,36 @@ +[options] +girs_dir = "./gir-files" +library = "LightDM" +version = "1" +min_cfg_version = "1" +target_path = "." +work_mode = "normal" +generate_safety_asserts = false +deprecate_by_min_version = true +single_version_file = true + +generate = [ + "LightDM.Greeter", + "LightDM.Language", + "LightDM.Layout", + "LightDM.Session", + "LightDM.User", + "LightDM.UserList", + "LightDM.GreeterError", + "LightDM.PromptType", + "LightDM.MessageType", + "LightDM.*" +] + +manual = [ + "GLib.Error", + "GLib.Quark", + "Gio.AsyncResult", + "Gio.AsyncReadyCallback", + "Gio.Cancellable" +] + +builders = [ + "LightDM.LanguageBuilder", + "LightDM.LayoutBuilder" +] diff --git a/gir-files/.github/FUNDING.yml b/gir-files/.github/FUNDING.yml new file mode 100644 index 0000000..1d8307f --- /dev/null +++ b/gir-files/.github/FUNDING.yml @@ -0,0 +1 @@ +open_collective: gtk-rs diff --git a/gir-files/.gitignore b/gir-files/.gitignore new file mode 100644 index 0000000..ac2281f --- /dev/null +++ b/gir-files/.gitignore @@ -0,0 +1 @@ +*.rnc diff --git a/gir-files/.travis.yml b/gir-files/.travis.yml new file mode 100644 index 0000000..a16ddd5 --- /dev/null +++ b/gir-files/.travis.yml @@ -0,0 +1,13 @@ +dist: xenial +language: rust +addons: + apt: + packages: + - libgtk-3-dev + - libssh2-1-dev +script: + - git clone https://github.com/gtk-rs/gir + - git clone https://github.com/gtk-rs/sys + - cd gir && cargo build --release && cd .. + - ./gir/target/release/gir -c sys/conf/gir-gtk.toml -m sys -o sys/gtk-sys/ -d . + - ./gir/target/release/gir -c sys/conf/gir-gtk4.toml -m sys -o sys/gtk4-sys/ -d . diff --git a/gir-files/Atk-1.0.gir b/gir-files/Atk-1.0.gir new file mode 100644 index 0000000..811b5cd --- /dev/null +++ b/gir-files/Atk-1.0.gir @@ -0,0 +1,15248 @@ + + + + + + + + + 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() + + + + + + + + + #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. + + + + + #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. + + + + + + + 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. + 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. + 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. + + + + + + Makes an object visible on the screen at a given position 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. + + + + + + + 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. + 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. + 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. + + + + + + Makes an object visible on the screen at a given position 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 bposition 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. + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + 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 + + + + + + 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. + + + + + + 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 + + + + + + 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. + + + + + + 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. + + + + + + + + + + + + + + + a string indicating the document type + + + + + a #GObject instance that implements AtkDocumentIface + + + + + + + + + + a %gpointer that points to an instance of the DOM. + + + + + a #GObject instance that implements AtkDocumentIface + + + + + + + + + + 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 + + + + + + + + + + An AtkAttributeSet containing the explicitly + set name-value-pair attributes associated with this document + as a whole. + + + + + a #GObject instance that implements AtkDocumentIface + + + + + + + + + + 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. + + + + + + + + + + %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. + + + + + + + + + + the current page number inside @document, or -1 if + not implemented, not know by the implementor, or irrelevant. + + + + + the #AtkDocument + + + + + + + + + + total page count of @document, or -1 if not implemented, + not know by the implementor or irrelevant. + + + + + the #AtkDocument + + + + + + + + #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 also: #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 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 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. 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 (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 + + + + + + + + + + + + + + + + + + + + + + + + AtkHyperlinkImpl allows AtkObjects to refer to their associated +AtkHyperlink instance, if one exists. AtkHyperlinkImpl differs +from AtkHyperlink in that AtkHyperlinkImpl is an interface, whereas +AtkHyperlink is a object type. The AtkHyperlinkImpl interface +allows a client to query an AtkObject for the availability of an +associated AtkHyperlink instance, and obtain that instance. It is +thus particularly useful in cases where embedded content or inline +content within a text object is present, since the embedding text +object implements AtkHypertext and the inline/embedded objects are +exposed as children which implement AtkHyperlinkImpl, in addition +to their being obtainable via AtkHypertext:getLink followed by +AtkHyperlink:getObject. + +The AtkHyperlinkImpl interface should be supported by objects +exposed within the hierarchy as children of an AtkHypertext +container which correspond to "links" or embedded content within +the text. HTML anchors are not, for instance, normally exposed +this way, but embedded images and components which appear inline in +the content of a text object are. The AtkHyperlinkIface interface +allows a means of determining which children are hyperlinks in this +sense of the word, and for obtaining their corresponding +AtkHyperlink object, from which the embedding range, URI, etc. can +be obtained. + +To some extent this interface exists because, for historical +reasons, AtkHyperlink was defined as an object type, not an +interface. Thus, in order to interact with AtkObjects via +AtkHyperlink semantics, a new interface was required. + + + 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 + + + + 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. + + + + + #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. + + + + + + + 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). + + + + + + + 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. + + + + + + + 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). + + + + + + + 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 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. + + + + 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 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. + + + + + + + + + + + + + an AtkMisc instance for this application. + + + + + + + + + + + + + + an AtkMisc instance for this application. + + + + + + + + + + + + + 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. 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 + + + + + + + + + + + + + + + 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 also: #AtkObjectFactory, #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 + + + + + + + + + + + + + + + + + + + + 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 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 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 signal "children-changed" is emitted when a child is added or +removed form 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 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 + + + + + + + + + + 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 + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + See #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. + + + + + #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. + + + + + 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 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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) + + + 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 the top + left corner of the window. + + + Scroll the object vertically and horizontally to the + bottom right corner of the window. + + + Scroll the object vertically to the top edge of the + window. + + + Scroll the object vertically to the bottom edge of + the window. + + + Scroll the object vertically and horizontally to the + left edge of the window. + + + Scroll the object vertically and horizontally 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. + + + + #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 + + + + + + + + + + + + + + + + + + + + + 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. + + + + 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 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 + + + 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. + + + + + + + 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. + + + + + + + + + + + + + + + + + #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. + + + + + + + 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 also #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. + + + + + + + + + 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 + + + + + + + + + + a GPtrArray of AtkObjects +representing the column header cells. + + + + + + + a GObject instance that implements AtkTableCellIface + + + + + + + + + + TRUE if successful; FALSE otherwise. + + + + + a GObject instance that implements AtkTableCellIface + + + + the row of the given cell. + + + + the column of the given 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 + + + + + + + + + + a GPtrArray of AtkObjects +representing the row header cells. + + + + + + + a GObject instance that implements AtkTableCellIface + + + + + + + + + + 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. + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 + + + + + + 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. + + + + + + + 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 @text visible on the screen by scrolling all necessary parents. + +Contrary to atk_text_set_position, this does not actually move +@text 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 #AtkText + + + + start position + + + + end position, or -1 for the end of the string. + + + + specify where the object should be made visible. + + + + + + Makes an object visible on the screen at a given position by scrolling all +necessary parents. + + + whether scrolling was successful. + + + + + an #AtkText + + + + start position + + + + end position, or -1 for the end of the string. + + + + 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. + + + %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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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. + + + + + + + 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 @text visible on the screen by scrolling all necessary parents. + +Contrary to atk_text_set_position, this does not actually move +@text 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 #AtkText + + + + start position + + + + end position, or -1 for the end of the string. + + + + specify where the object should be made visible. + + + + + + Makes an object visible on the screen at a given position by scrolling all +necessary parents. + + + whether scrolling was successful. + + + + + an #AtkText + + + + start position + + + + end position, or -1 for the end of the string. + + + + 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. + + + %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 + + + "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" + + + 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. + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + 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 position + + + + end position, or -1 for the end of the string. + + + + specify where the object should be made visible. + + + + + + + + + + whether scrolling was successful. + + + + + an #AtkText + + + + start position + + + + end position, or -1 for the end of the string. + + + + 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 + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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). + + + + + #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. + + + + + + + + + + + + + + + + + + + a GObject instance that implements AtkValueIface + + + + a #GValue representing the current accessible value + + + + + + + + + + + + + + a GObject instance that implements AtkValueIface + + + + a #GValue representing the maximum accessible value + + + + + + + + + + + + + + a GObject instance that implements AtkValueIface + + + + a #GValue representing the minimum accessible value + + + + + + + + + + %TRUE if new value is successfully set, %FALSE otherwise. + + + + + a GObject instance that implements AtkValueIface + + + + a #GValue which is the desired new accessible value. + + + + + + + + + + + + + + a GObject instance that implements AtkValueIface + + + + a #GValue representing the minimum increment by which the accessible value may be changed + + + + + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + the minimum increment by which the value of this +object may be changed. zero if undefined. + + + + + a GObject instance that implements AtkValueIface + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + #AtkWindow should be implemented by the UI elements that represent +a top-level window, such as the main window of an application or +dialog. + + + + 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 + + + + + + diff --git a/gir-files/DBus-1.0.gir b/gir-files/DBus-1.0.gir new file mode 100644 index 0000000..a85e482 --- /dev/null +++ b/gir-files/DBus-1.0.gir @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/DBusGLib-1.0.gir b/gir-files/DBusGLib-1.0.gir new file mode 100644 index 0000000..2126191 --- /dev/null +++ b/gir-files/DBusGLib-1.0.gir @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/gir-files/GIRepository-2.0.gir b/gir-files/GIRepository-2.0.gir new file mode 100644 index 0000000..3dd14bf --- /dev/null +++ b/gir-files/GIRepository-2.0.gir @@ -0,0 +1,4326 @@ + + + + + + + + + Represents an argument. + + + + + Represents a callable, either #GIFunctionInfo, #GICallbackInfo or +#GIVFuncInfo. + + + + + Represents a callback, eg arguments and return value. + + + + + Represents a constant. + + + + + Represents an enum or a flag. + + + + + Represents a field of a #GIStructInfo or a #GIUnionInfo. + + + + + Represents a function, eg arguments and return value. + + + + + Represents an interface. + + + + + Represents an object. + + + + + Represents a property of a #GIObjectInfo or a #GIInterfaceInfo. + + + + + Represent a registered type. + + + + + Represents a signal. + + + + + Represents a struct. + + + + + Represents type information, direction, transfer etc. + + + + + Represents a union. + + + + + Represents a virtual function. + + + + + Represents a enum value of a #GIEnumInfo. + + + + + Stores an argument of varying type + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + + The type of array in a #GITypeInfo. + + + a C array, char[] for instance + + + a @GArray array + + + a #GPtrArray array + + + a #GByteArray array + + + + An opaque structure used to iterate over attributes +in a #GIBaseInfo struct. + + + + + + + + + + + + + + + + GIBaseInfo is the common base struct of all other *Info structs +accessible through the #GIRepository API. +All other structs can be casted to a #GIBaseInfo, for instance: +<example> +<title>Casting a #GIFunctionInfo to #GIBaseInfo</title> +<programlisting> + GIFunctionInfo *function_info = ...; + GIBaseInfo *info = (GIBaseInfo*)function_info; +</programlisting> +</example> +Most #GIRepository APIs returning a #GIBaseInfo is actually creating a new struct, in other +words, g_base_info_unref() has to be called when done accessing the data. +GIBaseInfos are normally accessed by calling either +g_irepository_find_by_name(), g_irepository_find_by_gtype() or g_irepository_get_info(). + +<example> +<title>Getting the Button of the Gtk typelib</title> +<programlisting> + GIBaseInfo *button_info = g_irepository_find_by_name(NULL, "Gtk", "Button"); + ... use button_info ... + g_base_info_unref(button_info); +</programlisting> +</example> + +<refsect1 id="gi-gibaseinfo.struct-hierarchy" role="struct_hierarchy"> +<title role="struct_hierarchy.title">Struct hierarchy</title> +<synopsis> + GIBaseInfo + +----<link linkend="gi-GIArgInfo">GIArgInfo</link> + +----<link linkend="gi-GICallableInfo">GICallableInfo</link> + +----<link linkend="gi-GIConstantInfo">GIConstantInfo</link> + +----<link linkend="gi-GIFieldInfo">GIFieldInfo</link> + +----<link linkend="gi-GIPropertyInfo">GIPropertyInfo</link> + +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link> + +----<link linkend="gi-GITypeInfo">GITypeInfo</link> +</synopsis> +</refsect1> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Compare two #GIBaseInfo. + +Using pointer comparison is not practical since many functions return +different instances of #GIBaseInfo that refers to the same part of the +TypeLib; use this function instead to do #GIBaseInfo comparisons. + + + %TRUE if and only if @info1 equals @info2. + + + + + a #GIBaseInfo + + + + a #GIBaseInfo + + + + + + Retrieve an arbitrary attribute associated with this node. + + + The value of the attribute, or %NULL if no such attribute exists + + + + + a #GIBaseInfo + + + + a freeform string naming an attribute + + + + + + Obtain the container of the @info. The container is the parent +GIBaseInfo. For instance, the parent of a #GIFunctionInfo is an +#GIObjectInfo or #GIInterfaceInfo. + + + the container + + + + + a #GIBaseInfo + + + + + + Obtain the name of the @info. What the name represents depends on +the #GIInfoType of the @info. For instance for #GIFunctionInfo it is +the name of the function. + + + the name of @info or %NULL if it lacks a name. + + + + + a #GIBaseInfo + + + + + + Obtain the namespace of @info. + + + the namespace + + + + + a #GIBaseInfo + + + + + + Obtain the info type of the GIBaseInfo. + + + the info type of @info + + + + + a #GIBaseInfo + + + + + + Obtain the typelib this @info belongs to + + + the typelib. + + + + + a #GIBaseInfo + + + + + + Obtain whether the @info is represents a metadata which is +deprecated or not. + + + %TRUE if deprecated + + + + + a #GIBaseInfo + + + + + + Iterate over all attributes associated with this node. The iterator +structure is typically stack allocated, and must have its first +member initialized to %NULL. Attributes are arbitrary namespaced key–value +pairs which can be attached to almost any item. They are intended for use +by software higher in the toolchain than bindings, and are distinct from +normal GIR annotations. + +Both the @name and @value should be treated as constants +and must not be freed. + +<example> +<title>Iterating over attributes</title> +<programlisting> +void +print_attributes (GIBaseInfo *info) +{ + GIAttributeIter iter = { 0, }; + char *name; + char *value; + while (g_base_info_iterate_attributes (info, &iter, &name, &value)) + { + g_print ("attribute name: %s value: %s", name, value); + } +} +</programlisting> +</example> + + + %TRUE if there are more attributes + + + + + a #GIBaseInfo + + + + a #GIAttributeIter structure, must be initialized; see below + + + + Returned name, must not be freed + + + + Returned name, must not be freed + + + + + + Increases the reference count of @info. + + + the same @info. + + + + + a #GIBaseInfo + + + + + + Decreases the reference count of @info. When its reference count +drops to 0, the info is freed. + + + + + + + a #GIBaseInfo + + + + + + + Checks the version of the girepository library that is being compiled +against. + + + + the major version to check for + + + the minor version to check for + + + the micro version to check for + + + + + The direction of a #GIArgInfo. + + + in argument. + + + out argument. + + + in and out argument. + + + + Flags for a #GIFieldInfo. + + + field is readable. + + + field is writable. + + + + Flags for a #GIFunctionInfo struct. + + + is a method. + + + is a constructor. + + + is a getter of a #GIPropertyInfo. + + + is a setter of a #GIPropertyInfo. + + + represents a virtual function. + + + the function may throw an error. + + + + + + + + + + + + + + + + + + + + + + + + + Checks if @info is a GIArgInfo. + + + + an info structure + + + + + Checks if @info is a #GICallableInfo or derived from it. + + + + an info structure + + + + + Checks if @info is a #GIConstantInfo. + + + + an info structure + + + + + Checks if @info is a #GIEnumInfo. + + + + an info structure + + + + + Checks if @info is a #GIFieldInfo. + + + + an info structure + + + + + Checks if @info is a #GIFunctionInfo. + + + + an info structure + + + + + Checks if @info is a #GIInterfaceInfo. + + + + an info structure + + + + + + + + + + + + + + + + + + + Checks if @info is a #GIObjectInfo. + + + + an info structure + + + + + Checks if @info is a #GIPropertyInfo. + + + + an info structure + + + + + Checks if @info is a #GIRegisteredTypeInfo or derived from it. + + + + an info structure + + + + + Checks if @info is a #GISignalInfo. + + + + an info structure + + + + + Checks if @info is a #GIStructInfo. + + + + an info structure + + + + + Checks if @info is a #GITypeInfo. + + + + an info structure + + + + + Checks if @info is a #GIUnionInfo. + + + + an info structure + + + + + Checks if @info is a #GIValueInfo. + + + + an info structure + + + + + Checks if @info is a #GIVfuncInfo. + + + + an info structure + + + + + The type of a GIBaseInfo struct. + + + invalid type + + + function, see #GIFunctionInfo + + + callback, see #GIFunctionInfo + + + struct, see #GIStructInfo + + + boxed, see #GIStructInfo or #GIUnionInfo + + + enum, see #GIEnumInfo + + + flags, see #GIEnumInfo + + + object, see #GIObjectInfo + + + interface, see #GIInterfaceInfo + + + contant, see #GIConstantInfo + + + deleted, used to be GI_INFO_TYPE_ERROR_DOMAIN. + + + union, see #GIUnionInfo + + + enum value, see #GIValueInfo + + + signal, see #GISignalInfo + + + virtual function, see #GIVFuncInfo + + + GObject property, see #GIPropertyInfo + + + struct or union field, see #GIFieldInfo + + + argument of a function or callback, see #GIArgInfo + + + type information, see #GITypeInfo + + + unresolved type, a type which is not present in + the typelib, or any of its dependencies. + + + + The major version number of the girepository library. + + + + + The micro version number of the girepository library. + + + + + The minor version number of the girepository library. + + + + + Extract an object instance out of @value + + + the object instance + + + + + a #GValue + + + + + + Increases the reference count of an object instance. + + + the object instance + + + + + object instance pointer + + + + + + Update @value and attach the object instance pointer @object to it. + + + + + + + a #GValue + + + + object instance pointer + + + + + + Decreases the reference count of an object instance. + + + + + + + object instance pointer + + + + + + #GIRepository is used to manage repositories of namespaces. Namespaces +are represented on disk by type libraries (.typelib files). + +### Discovery of type libraries + +#GIRepository will typically look for a `girepository-1.0` directory +under the library directory used when compiling gobject-introspection. + +It is possible to control the search paths programmatically, using +g_irepository_prepend_search_path(). It is also possible to modify +the search paths by using the `GI_TYPELIB_PATH` environment variable. +The environment variable takes precedence over the default search path +and the g_irepository_prepend_search_path() calls. + + + + + + + + + + + + + + + + + + + Returns the singleton process-global default #GIRepository. It is +not currently supported to have multiple repositories in a +particular process, but this function is provided in the unlikely +eventuality that it would become possible, and as a convenience for +higher level language bindings to conform to the GObject method +call conventions. + +All methods on #GIRepository also accept %NULL as an instance +parameter to mean this default repository, which is usually more +convenient for C. + + + The global singleton #GIRepository + + + + + Obtain the option group for girepository, it's used +by the dumper and for programs that wants to provide +introspection information + + + the option group + + + + + Returns the current search path #GIRepository will use when loading +typelib files. The list is internal to #GIRepository and should not +be freed, nor should its string elements. + + + #GSList of strings + + + + + + + + + + + + + + + + + + Prepends @directory to the typelib search path. + +See also: g_irepository_get_search_path(). + + + + + + + directory name to prepend to the typelib + search path + + + + + + Obtain an unordered list of versions (either currently loaded or +available) for @namespace_ in this @repository. + + + the array of versions. + + + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + GI namespace, e.g. "Gtk" + + + + + + Searches for the enum type corresponding to the given #GError +domain. Before calling this function for a particular namespace, +you must call g_irepository_require() once to load the namespace, or +otherwise ensure the namespace has already been loaded. + + + #GIEnumInfo representing metadata about @domain's +enum type, or %NULL + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + a #GError domain + + + + + + Searches all loaded namespaces for a particular #GType. Note that +in order to locate the metadata, the namespace corresponding to +the type must first have been loaded. There is currently no +mechanism for determining the namespace which corresponds to an +arbitrary GType - thus, this function will operate most reliably +when you know the GType to originate from be from a loaded namespace. + + + #GIBaseInfo representing metadata about @type, or %NULL + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + GType to search for + + + + + + Searches for a particular entry in a namespace. Before calling +this function for a particular namespace, you must call +g_irepository_require() once to load the namespace, or otherwise +ensure the namespace has already been loaded. + + + #GIBaseInfo representing metadata about @name, or %NULL + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace which will be searched + + + + Entry name to find + + + + + + This function returns the "C prefix", or the C level namespace +associated with the given introspection namespace. Each C symbol +starts with this prefix, as well each #GType in the library. + +Note: The namespace must have already been loaded using a function +such as g_irepository_require() before calling this function. + + + C namespace prefix, or %NULL if none associated + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace to inspect + + + + + + Return an array of all (transitive) versioned dependencies for +@namespace_. Returned strings are of the form +<code>namespace-version</code>. + +Note: @namespace_ must have already been loaded using a function +such as g_irepository_require() before calling this function. + +To get only the immediate dependencies for @namespace_, use +g_irepository_get_immediate_dependencies(). + + + Zero-terminated string array of all versioned + dependencies + + + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace of interest + + + + + + Return an array of the immediate versioned dependencies for @namespace_. +Returned strings are of the form <code>namespace-version</code>. + +Note: @namespace_ must have already been loaded using a function +such as g_irepository_require() before calling this function. + +To get the transitive closure of dependencies for @namespace_, use +g_irepository_get_dependencies(). + + + Zero-terminated string array of immediate versioned + dependencies + + + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace of interest + + + + + + This function returns a particular metadata entry in the +given namespace @namespace_. The namespace must have +already been loaded before calling this function. +See g_irepository_get_n_infos() to find the maximum number of +entries. + + + #GIBaseInfo containing metadata + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace to inspect + + + + 0-based offset into namespace metadata for entry + + + + + + Return the list of currently loaded namespaces. + + + List of namespaces + + + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + + + This function returns the number of metadata entries in +given namespace @namespace_. The namespace must have +already been loaded before calling this function. + + + number of metadata entries + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace to inspect + + + + + + Look up the implemented interfaces for @gtype. This function +cannot fail per se; but for a totally "unknown" #GType, it may +return 0 implemented interfaces. + +The semantics of this function are designed for a dynamic binding, +where in certain cases (such as a function which returns an +interface which may have "hidden" implementation classes), not all +data may be statically known, and will have to be determined from +the #GType of the object. An example is g_file_new_for_path() +returning a concrete class of #GLocalFile, which is a #GType we +see at runtime, but not statically. + + + + + + + a #GIRepository, or %NULL for the default repository + + + + a #GType whose fundamental type is G_TYPE_OBJECT + + + + Number of interfaces + + + + Interfaces for @gtype + + + + + + + + This function returns a comma-separated list of paths to the +shared C libraries associated with the given namespace @namespace_. +There may be no shared library path associated, in which case this +function will return %NULL. + +Note: The namespace must have already been loaded using a function +such as g_irepository_require() before calling this function. + + + Comma-separated list of paths to shared libraries, + or %NULL if none are associated + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace to inspect + + + + + + If namespace @namespace_ is loaded, return the full path to the +.typelib file it was loaded from. If the typelib for +namespace @namespace_ was included in a shared library, return +the special string "&lt;builtin&gt;". + + + Filesystem path (or $lt;builtin$gt;) if successful, %NULL if namespace is not loaded + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + GI namespace to use, e.g. "Gtk" + + + + + + This function returns the loaded version associated with the given +namespace @namespace_. + +Note: The namespace must have already been loaded using a function +such as g_irepository_require() before calling this function. + + + Loaded version + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace to inspect + + + + + + Check whether a particular namespace (and optionally, a specific +version thereof) is currently loaded. This function is likely to +only be useful in unusual circumstances; in order to act upon +metadata in the namespace, you should call g_irepository_require() +instead which will ensure the namespace is loaded, and return as +quickly as this function will if it has already been loaded. + + + %TRUE if namespace-version is loaded, %FALSE otherwise + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Namespace of interest + + + + Required version, may be %NULL for latest + + + + + + TODO + + + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + TODO + + + + TODO + + + + + + Force the namespace @namespace_ to be loaded if it isn't already. +If @namespace_ is not loaded, this function will search for a +".typelib" file using the repository search path. In addition, a +version @version of namespace may be specified. If @version is +not specified, the latest will be used. + + + a pointer to the #GITypelib if successful, %NULL otherwise + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + GI namespace to use, e.g. "Gtk" + + + + Version of namespace, may be %NULL for latest + + + + Set of %GIRepositoryLoadFlags, may be 0 + + + + + + Force the namespace @namespace_ to be loaded if it isn't already. +If @namespace_ is not loaded, this function will search for a +".typelib" file within the private directory only. In addition, a +version @version of namespace should be specified. If @version is +not specified, the latest will be used. + + + a pointer to the #GITypelib if successful, %NULL otherwise + + + + + A #GIRepository or %NULL for the singleton + process-global default #GIRepository + + + + Private directory where to find the requested typelib + + + + GI namespace to use, e.g. "Gtk" + + + + Version of namespace, may be %NULL for latest + + + + Set of %GIRepositoryLoadFlags, may be 0 + + + + + + + + + + + + + + + + + + + An error code used with #G_IREPOSITORY_ERROR in a #GError returned +from a #GIRepository routine. + + + the typelib could not be found. + + + the namespace does not match the + requested namespace. + + + the version of the + typelib does not match the requested version. + + + the library used by the typelib + could not be found. + + + + Flags that control how a typelib is loaded. + + + Lazily load the typelib. + + + + + + + Scope type of a #GIArgInfo representing callback, determines how the +callback is invoked and is used to decided when the invoke structs +can be freed. + + + The argument is not of callback type. + + + The callback and associated user_data is only +used during the call to this function. + + + The callback and associated user_data is +only used until the callback is invoked, and the callback. +is invoked always exactly once. + + + The callback and and associated +user_data is used until the caller is notfied via the destroy_notify. + + + + Checks if @tag is a basic type. + + + + a type tag + + + + + TODO + + + + + The transfer is the exchange of data between two parts, from the callee to +the caller. The callee is either a function/method/signal or an +object/interface where a property is defined. The caller is the side +accessing a property or calling a function. +#GITransfer specifies who's responsible for freeing the resources after the +ownership transfer is complete. In case of a containing type such as a list, +an array or a hash table the container itself is specified differently from +the items within the container itself. Each container is freed differently, +check the documentation for the types themselves for information on how to +free them. + + + transfer nothing from the callee (function or the type +instance the property belongs to) to the caller. The callee retains the +ownership of the transfer and the caller doesn't need to do anything to free +up the resources of this transfer. + + + transfer the container (list, array, hash table) from +the callee to the caller. The callee retains the ownership of the individual +items in the container and the caller has to free up the container resources +(g_list_free()/g_hash_table_destroy() etc) of this transfer. + + + transfer everything, eg the container and its +contents from the callee to the caller. This is the case when the callee +creates a copy of all the data it returns. The caller is responsible for +cleaning up the container and item resources of this transfer. + + + + The type tag of a #GITypeInfo. + + + void + + + boolean + + + 8-bit signed integer + + + 8-bit unsigned integer + + + 16-bit signed integer + + + 16-bit unsigned integer + + + 32-bit signed integer + + + 32-bit unsigned integer + + + 64-bit signed integer + + + 64-bit unsigned integer + + + float + + + double floating point + + + a #GType + + + a UTF-8 encoded string + + + a filename, encoded in the same encoding + as the native filesystem is using. + + + an array + + + an extended interface object + + + a #GList + + + a #GSList + + + a #GHashTable + + + a #GError + + + Unicode character + + + + TODO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Represents a unresolved type in a typelib. + + + + Flags of a #GIVFuncInfo struct. + + + chains up to the parent type + + + overrides + + + does not override + + + Includes a #GError + + + + Obtain the index of the user data argument. This is only valid +for arguments which are callbacks. + + + index of the user data argument or -1 if there is none + + + + + a #GIArgInfo + + + + + + Obtains the index of the #GDestroyNotify argument. This is only valid +for arguments which are callbacks. + + + index of the #GDestroyNotify argument or -1 if there is none + + + + + a #GIArgInfo + + + + + + Obtain the direction of the argument. Check #GIDirection for possible +direction values. + + + the direction + + + + + a #GIArgInfo + + + + + + Obtain the ownership transfer for this argument. +#GITransfer contains a list of possible values. + + + the transfer + + + + + a #GIArgInfo + + + + + + Obtain the scope type for this argument. The scope type explains +how a callback is going to be invoked, most importantly when +the resources required to invoke it can be freed. +#GIScopeType contains a list of possible values. + + + the scope type + + + + + a #GIArgInfo + + + + + + Obtain the type information for @info. + + + the #GITypeInfo holding the type + information for @info, free it with g_base_info_unref() + when done. + + + + + a #GIArgInfo + + + + + + Obtain if the argument is a pointer to a struct or object that will +receive an output of a function. The default assumption for +%GI_DIRECTION_OUT arguments which have allocation is that the +callee allocates; if this is %TRUE, then the caller must allocate. + + + %TRUE if caller is required to have allocated the argument + + + + + a #GIArgInfo + + + + + + Obtain if the argument is optional. For 'out' arguments this means +that you can pass %NULL in order to ignore the result. + + + %TRUE if it is an optional argument + + + + + a #GIArgInfo + + + + + + Obtain if the argument is a return value. It can either be a +parameter or a return value. + + + %TRUE if it is a return value + + + + + a #GIArgInfo + + + + + + Obtain if an argument is only useful in C. + + + %TRUE if argument is only useful in C. + + + + + a #GIArgInfo + + + + + + Obtain information about a the type of given argument @info; this +function is a variant of g_arg_info_get_type() designed for stack +allocation. + +The initialized @type must not be referenced after @info is deallocated. + + + + + + + a #GIArgInfo + + + + Initialized with information about type of @info + + + + + + Obtain if the type of the argument includes the possibility of %NULL. +For 'in' values this means that %NULL is a valid value. For 'out' +values, this means that %NULL may be returned. + +See also g_arg_info_is_optional(). + + + %TRUE if the value may be %NULL + + + + + a #GIArgInfo + + + + + + TODO + + + %TRUE if this #GICallableInfo can throw a #GError + + + + + a #GICallableInfo + + + + + + Obtain information about a particular argument of this callable. + + + the #GIArgInfo. Free it with +g_base_info_unref() when done. + + + + + a #GICallableInfo + + + + the argument index to fetch + + + + + + See whether the caller owns the return value of this callable. +#GITransfer contains a list of possible transfer values. + + + the transfer mode for the return value of the callable + + + + + a #GICallableInfo + + + + + + Obtains the ownership transfer for the instance argument. +#GITransfer contains a list of possible transfer values. + + + the transfer mode of the instance argument + + + + + a #GICallableInfo + + + + + + Obtain the number of arguments (both IN and OUT) for this callable. + + + The number of arguments this callable expects. + + + + + a #GICallableInfo + + + + + + Retrieve an arbitrary attribute associated with the return value. + + + The value of the attribute, or %NULL if no such attribute exists + + + + + a #GICallableInfo + + + + a freeform string naming an attribute + + + + + + Obtain the return type of a callable item as a #GITypeInfo. + + + the #GITypeInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GICallableInfo + + + + + + TODO + + + + + + + TODO + + + + TODO + + + + TODO + + + + + + TODO + + + + TODO + + + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + + + Determines if the callable info is a method. For #GIVFuncInfo<!-- -->s, +#GICallbackInfo<!-- -->s, and #GISignalInfo<!-- -->s, +this is always true. Otherwise, this looks at the %GI_FUNCTION_IS_METHOD +flag on the #GIFunctionInfo. + +Concretely, this function returns whether g_callable_info_get_n_args() +matches the number of arguments in the raw C method. For methods, there +is one more C argument than is exposed by introspection: the "self" +or "this" object. + + + %TRUE if @info is a method, %FALSE otherwise + + + + + a #GICallableInfo + + + + + + Iterate over all attributes associated with the return value. The +iterator structure is typically stack allocated, and must have its +first member initialized to %NULL. + +Both the @name and @value should be treated as constants +and must not be freed. + +See g_base_info_iterate_attributes() for an example of how to use a +similar API. + + + %TRUE if there are more attributes + + + + + a #GICallableInfo + + + + a #GIAttributeIter structure, must be initialized; see below + + + + Returned name, must not be freed + + + + Returned name, must not be freed + + + + + + Obtain information about a particular argument of this callable; this +function is a variant of g_callable_info_get_arg() designed for stack +allocation. + +The initialized @arg must not be referenced after @info is deallocated. + + + + + + + a #GICallableInfo + + + + the argument index to fetch + + + + Initialize with argument number @n + + + + + + Obtain information about a return value of callable; this +function is a variant of g_callable_info_get_return_type() designed for stack +allocation. + +The initialized @type must not be referenced after @info is deallocated. + + + + + + + a #GICallableInfo + + + + Initialized with return type of @info + + + + + + See if a callable could return %NULL. + + + %TRUE if callable could return %NULL + + + + + a #GICallableInfo + + + + + + See if a callable's return value is only useful in C. + + + %TRUE if return value is only useful in C. + + + + + a #GICallableInfo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Free the value returned from g_constant_info_get_value(). + + + + + + + a #GIConstantInfo + + + + the argument + + + + + + Obtain the type of the constant as a #GITypeInfo. + + + the #GITypeInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIConstantInfo + + + + + + Obtain the value associated with the #GIConstantInfo and store it in the +@value parameter. @argument needs to be allocated before passing it in. +The size of the constant value stored in @argument will be returned. +Free the value with g_constant_info_free_value(). + + + size of the constant + + + + + a #GIConstantInfo + + + + an argument + + + + + + Obtain the string form of the quark for the error domain associated with +this enum, if any. + + + the string form of the error domain associated +with this enum, or %NULL. + + + + + a #GIEnumInfo + + + + + + Obtain an enum type method at index @n. + + + the #GIFunctionInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIEnumInfo + + + + index of method to get + + + + + + Obtain the number of methods that this enum type has. + + + number of methods + + + + + a #GIEnumInfo + + + + + + Obtain the number of values this enumeration contains. + + + the number of enumeration values + + + + + a #GIEnumInfo + + + + + + Obtain the tag of the type used for the enum in the C ABI. This will +will be a signed or unsigned integral type. + +Note that in the current implementation the width of the type is +computed correctly, but the signed or unsigned nature of the type +may not match the sign of the type used by the C compiler. + + + the storage type for the enumeration + + + + + a #GIEnumInfo + + + + + + Obtain a value for this enumeration. + + + the enumeration value or %NULL if type tag is wrong, +free the struct with g_base_info_unref() when done. + + + + + a #GIEnumInfo + + + + index of value to fetch + + + + + + Reads a field identified by a #GIFieldInfo from a C structure or +union. This only handles fields of simple C types. It will fail +for a field of a composite type like a nested structure or union +even if that is actually readable. + + + %TRUE if reading the field succeeded, otherwise %FALSE + + + + + a #GIFieldInfo + + + + pointer to a block of memory representing a C structure or union + + + + a #GIArgument into which to store the value retrieved + + + + + + Obtain the flags for this #GIFieldInfo. See #GIFieldInfoFlags for possible +flag values. + + + the flags + + + + + a #GIFieldInfo + + + + + + Obtain the offset in bytes of the field member, this is relative +to the beginning of the struct or union. + + + the field offset + + + + + a #GIFieldInfo + + + + + + Obtain the size in bits of the field member, this is how +much space you need to allocate to store the field. + + + the field size + + + + + a #GIFieldInfo + + + + + + Obtain the type of a field as a #GITypeInfo. + + + the #GITypeInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIFieldInfo + + + + + + Writes a field identified by a #GIFieldInfo to a C structure or +union. This only handles fields of simple C types. It will fail +for a field of a composite type like a nested structure or union +even if that is actually writable. Note also that that it will refuse +to write fields where memory management would by required. A field +with a type such as 'char *' must be set with a setter function. + + + %TRUE if writing the field succeeded, otherwise %FALSE + + + + + a #GIFieldInfo + + + + pointer to a block of memory representing a C structure or union + + + + a #GIArgument holding the value to store + + + + + + Obtain the #GIFunctionInfoFlags for the @info. + + + the flags + + + + + a #GIFunctionInfo + + + + + + Obtain the property associated with this #GIFunctionInfo. +Only #GIFunctionInfo with the flag %GI_FUNCTION_IS_GETTER or +%GI_FUNCTION_IS_SETTER have a property set. For other cases, +%NULL will be returned. + + + the property or %NULL if not set. Free it with +g_base_info_unref() when done. + + + + + a #GIFunctionInfo + + + + + + Obtain the symbol of the function. The symbol is the name of the +exported function, suitable to be used as an argument to +g_module_symbol(). + + + the symbol + + + + + a #GIFunctionInfo + + + + + + Obtain the virtual function associated with this #GIFunctionInfo. +Only #GIFunctionInfo with the flag %GI_FUNCTION_WRAPS_VFUNC has +a virtual function set. For other cases, %NULL will be returned. + + + the virtual function or %NULL if not set. +Free it by calling g_base_info_unref() when done. + + + + + a #GIFunctionInfo + + + + + + Invokes the function described in @info with the given +arguments. Note that inout parameters must appear in both +argument lists. This function uses dlsym() to obtain a pointer +to the function, so the library or shared object containing the +described function must either be linked to the caller, or must +have been g_module_symbol()<!-- -->ed before calling this function. + + + %TRUE if the function has been invoked, %FALSE if an + error occurred. + + + + + a #GIFunctionInfo describing the function to invoke + + + + an array of #GIArgument<!-- -->s, one for each in + parameter of @info. If there are no in parameter, @in_args + can be %NULL + + + + + + the length of the @in_args array + + + + an array of #GIArgument<!-- -->s, one for each out + parameter of @info. If there are no out parameters, @out_args + may be %NULL + + + + + + the length of the @out_args array + + + + return location for the return value of the + function. If the function returns void, @return_value may be + %NULL + + + + + + Returns the major version number of the girepository library. +(e.g. in version 1.58.2 this is 1.) + + + the major version number of the girepository library + + + + + Returns the micro version number of the girepository library. +(e.g. in version 1.58.2 this is 2.) + + + the micro version number of the girepository library + + + + + Returns the minor version number of the girepository library. +(e.g. in version 1.58.2 this is 58.) + + + the minor version number of the girepository library + + + + + TODO + + + TODO + + + + + TODO + + + + TODO + + + + TODO + + + + TODO + + + + + + Obtain a string representation of @type + + + the string + + + + + the info type + + + + + + Obtain a method of the interface type given a @name. %NULL will be +returned if there's no method available with that name. + + + the #GIFunctionInfo or %NULL if none found. +Free the struct by calling g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + name of method to obtain + + + + + + TODO + + + Info for the signal with name @name in @info, or +%NULL on failure. + + + + + a #GIInterfaceInfo + + + + Name of signal + + + + + + Locate a virtual function slot with name @name. See the documentation +for g_object_info_find_vfunc() for more information on virtuals. + + + the #GIVFuncInfo, or %NULL. Free it with +g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + The name of a virtual function to find. + + + + + + Obtain an interface type constant at index @n. + + + the #GIConstantInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + index of constant to get + + + + + + Returns the layout C structure associated with this #GInterface. + + + the #GIStructInfo or %NULL. Free it with +g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + + + Obtain an interface type method at index @n. + + + the #GIFunctionInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + index of method to get + + + + + + Obtain the number of constants that this interface type has. + + + number of constants + + + + + a #GIInterfaceInfo + + + + + + Obtain the number of methods that this interface type has. + + + number of methods + + + + + a #GIInterfaceInfo + + + + + + Obtain the number of prerequisites for this interface type. +A prerequisites is another interface that needs to be implemented for +interface, similar to an base class for GObjects. + + + number of prerequisites + + + + + a #GIInterfaceInfo + + + + + + Obtain the number of properties that this interface type has. + + + number of properties + + + + + a #GIInterfaceInfo + + + + + + Obtain the number of signals that this interface type has. + + + number of signals + + + + + a #GIInterfaceInfo + + + + + + Obtain the number of virtual functions that this interface type has. + + + number of virtual functions + + + + + a #GIInterfaceInfo + + + + + + Obtain an interface type prerequisites index @n. + + + the prerequisites as a #GIBaseInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + index of prerequisites to get + + + + + + Obtain an interface type property at index @n. + + + the #GIPropertyInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + index of property to get + + + + + + Obtain an interface type signal at index @n. + + + the #GISignalInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + index of signal to get + + + + + + Obtain an interface type virtual function at index @n. + + + the #GIVFuncInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIInterfaceInfo + + + + index of virtual function to get + + + + + + TODO + + TODO + + + + + An error occuring while invoking a function via +g_function_info_invoke(). + + + invokation failed, unknown error. + + + symbol couldn't be found in any of the +libraries associated with the typelib of the function. + + + the arguments provided didn't match +the expected arguments for the functions type signature. + + + + Obtain a method of the object type given a @name. %NULL will be +returned if there's no method available with that name. + + + the #GIFunctionInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + name of method to obtain + + + + + + Obtain a method of the object given a @name, searching both the +object @info and any interfaces it implements. %NULL will be +returned if there's no method available with that name. + +Note that this function does *not* search parent classes; you will have +to chain up if that's desired. + + + the #GIFunctionInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + name of method to obtain + + + + The implementor of the interface + + + + + + TODO + + + Info for the signal with name @name in @info, or %NULL on failure. + + + + + a #GIObjectInfo + + + + Name of signal + + + + + + Locate a virtual function slot with name @name. Note that the namespace +for virtuals is distinct from that of methods; there may or may not be +a concrete method associated for a virtual. If there is one, it may +be retrieved using g_vfunc_info_get_invoker(), otherwise %NULL will be +returned. +See the documentation for g_vfunc_info_get_invoker() for more +information on invoking virtuals. + + + the #GIVFuncInfo, or %NULL. Free it with +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + The name of a virtual function to find. + + + + + + Locate a virtual function slot with name @name, searching both the object +@info and any interfaces it implements. Note that the namespace for +virtuals is distinct from that of methods; there may or may not be a +concrete method associated for a virtual. If there is one, it may be +retrieved using g_vfunc_info_get_invoker(), otherwise %NULL will be +returned. + +Note that this function does *not* search parent classes; you will have +to chain up if that's desired. + + + the #GIVFuncInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + name of vfunc to obtain + + + + The implementor of the interface + + + + + + Obtain if the object type is an abstract type, eg if it cannot be +instantiated + + + %TRUE if the object type is abstract + + + + + a #GIObjectInfo + + + + + + Every #GObject has two structures; an instance structure and a class +structure. This function returns the metadata for the class structure. + + + the #GIStructInfo or %NULL. Free with +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + + + Obtain an object type constant at index @n. + + + the #GIConstantInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + index of constant to get + + + + + + Obtain an object type field at index @n. + + + the #GIFieldInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + index of field to get + + + + + + Obtain if the object type is of a fundamental type which is not +G_TYPE_OBJECT. This is mostly for supporting GstMiniObject. + + + %TRUE if the object type is a fundamental type + + + + + a #GIObjectInfo + + + + + + Obtain the symbol name of the function that should be called to convert +an object instance pointer of this object type to a GValue. +I's mainly used fundamental types. The type signature for the symbol +is %GIObjectInfoGetValueFunction, to fetch the function pointer +see g_object_info_get_get_value_function(). + + + the symbol or %NULL + + + + + a #GIObjectInfo + + + + + + Obtain a pointer to a function which can be used to +extract an instance of this object type out of a GValue. +This takes derivation into account and will reversely traverse +the base classes of this type, starting at the top type. + + + the function pointer or %NULL + + + + + a #GIObjectInfo + + + + + + Obtain an object type interface at index @n. + + + the #GIInterfaceInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + index of interface to get + + + + + + Obtain an object type method at index @n. + + + the #GIFunctionInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + index of method to get + + + + + + Obtain the number of constants that this object type has. + + + number of constants + + + + + a #GIObjectInfo + + + + + + Obtain the number of fields that this object type has. + + + number of fields + + + + + a #GIObjectInfo + + + + + + Obtain the number of interfaces that this object type has. + + + number of interfaces + + + + + a #GIObjectInfo + + + + + + Obtain the number of methods that this object type has. + + + number of methods + + + + + a #GIObjectInfo + + + + + + Obtain the number of properties that this object type has. + + + number of properties + + + + + a #GIObjectInfo + + + + + + Obtain the number of signals that this object type has. + + + number of signals + + + + + a #GIObjectInfo + + + + + + Obtain the number of virtual functions that this object type has. + + + number of virtual functions + + + + + a #GIObjectInfo + + + + + + Obtain the parent of the object type. + + + the #GIObjectInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + + + Obtain an object type property at index @n. + + + the #GIPropertyInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + index of property to get + + + + + + Obtain the symbol name of the function that should be called to ref this +object type. It's mainly used fundamental types. The type signature for +the symbol is %GIObjectInfoRefFunction, to fetch the function pointer +see g_object_info_get_ref_function(). + + + the symbol or %NULL + + + + + a #GIObjectInfo + + + + + + Obtain a pointer to a function which can be used to +increase the reference count an instance of this object type. +This takes derivation into account and will reversely traverse +the base classes of this type, starting at the top type. + + + the function pointer or %NULL + + + + + a #GIObjectInfo + + + + + + Obtain the symbol name of the function that should be called to convert +set a GValue giving an object instance pointer of this object type. +I's mainly used fundamental types. The type signature for the symbol +is %GIObjectInfoSetValueFunction, to fetch the function pointer +see g_object_info_get_set_value_function(). + + + the symbol or %NULL + + + + + a #GIObjectInfo + + + + + + Obtain a pointer to a function which can be used to +set a GValue given an instance of this object type. +This takes derivation into account and will reversely traverse +the base classes of this type, starting at the top type. + + + the function pointer or %NULL + + + + + a #GIObjectInfo + + + + + + Obtain an object type signal at index @n. + + + the #GISignalInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + index of signal to get + + + + + + Obtain the function which when called will return the GType +function for which this object type is registered. + + + the type init function + + + + + a #GIObjectInfo + + + + + + Obtain the name of the objects class/type. + + + name of the objects type + + + + + a #GIObjectInfo + + + + + + Obtain the symbol name of the function that should be called to unref this +object type. It's mainly used fundamental types. The type signature for +the symbol is %GIObjectInfoUnrefFunction, to fetch the function pointer +see g_object_info_get_unref_function(). + + + the symbol or %NULL + + + + + a #GIObjectInfo + + + + + + Obtain a pointer to a function which can be used to +decrease the reference count an instance of this object type. +This takes derivation into account and will reversely traverse +the base classes of this type, starting at the top type. + + + the function pointer or %NULL + + + + + a #GIObjectInfo + + + + + + Obtain an object type virtual function at index @n. + + + the #GIVFuncInfo. Free the struct by calling +g_base_info_unref() when done. + + + + + a #GIObjectInfo + + + + index of virtual function to get + + + + + + Obtain the flags for this property info. See #GParamFlags for +more information about possible flag values. + + + the flags + + + + + a #GIPropertyInfo + + + + + + Obtain the ownership transfer for this property. See #GITransfer for more +information about transfer values. + + + the transfer + + + + + a #GIPropertyInfo + + + + + + Obtain the type information for the property @info. + + + the #GITypeInfo, free it with +g_base_info_unref() when done. + + + + + a #GIPropertyInfo + + + + + + Obtain the #GType for this registered type or G_TYPE_NONE which a special meaning. +It means that either there is no type information associated with this @info or +that the shared library which provides the type_init function for this +@info cannot be called. + + + the #GType. + + + + + a #GIRegisteredTypeInfo + + + + + + Obtain the type init function for @info. The type init function is the +function which will register the GType within the GObject type system. +Usually this is not called by langauge bindings or applications, use +g_registered_type_info_get_g_type() directly instead. + + + the symbol name of the type init function, suitable for +passing into g_module_symbol(). + + + + + a #GIRegisteredTypeInfo + + + + + + Obtain the type name of the struct within the GObject type system. +This type can be passed to g_type_name() to get a #GType. + + + the type name + + + + + a #GIRegisteredTypeInfo + + + + + + Obtain the class closure for this signal if one is set. The class +closure is a virtual function on the type that the signal belongs to. +If the signal lacks a closure %NULL will be returned. + + + the class closure or %NULL + + + + + a #GISignalInfo + + + + + + Obtain the flags for this signal info. See #GSignalFlags for +more information about possible flag values. + + + the flags + + + + + a #GISignalInfo + + + + + + Obtain if the returning true in the signal handler will +stop the emission of the signal. + + + %TRUE if returning true stops the signal emission + + + + + a #GISignalInfo + + + + + + Obtain the type information for field named @name. + + + the #GIFieldInfo or %NULL if not found, +free it with g_base_info_unref() when done. + + + + + a #GIStructInfo + + + + a field name + + + + + + Obtain the type information for method named @name. + + + the #GIFunctionInfo, free it with g_base_info_unref() +when done. + + + + + a #GIStructInfo + + + + a method name + + + + + + Obtain the required alignment of the structure. + + + required alignment in bytes + + + + + a #GIStructInfo + + + + + + Obtain the type information for field with specified index. + + + the #GIFieldInfo, free it with g_base_info_unref() +when done. + + + + + a #GIStructInfo + + + + a field index + + + + + + Obtain the type information for method with specified index. + + + the #GIFunctionInfo, free it with g_base_info_unref() +when done. + + + + + a #GIStructInfo + + + + a method index + + + + + + Obtain the number of fields this structure has. + + + number of fields + + + + + a #GIStructInfo + + + + + + Obtain the number of methods this structure has. + + + number of methods + + + + + a #GIStructInfo + + + + + + Obtain the total size of the structure. + + + size of the structure in bytes + + + + + a #GIStructInfo + + + + + + TODO + + + TODO + + + + + TODO + + + + + + Return true if this structure represents the "class structure" for some +#GObject or #GInterface. This function is mainly useful to hide this kind of structure +from generated public APIs. + + + %TRUE if this is a class struct, %FALSE otherwise + + + + + a #GIStructInfo + + + + + + Obtain the fixed array size of the type. The type tag must be a +#GI_TYPE_TAG_ARRAY or -1 will returned. + + + the size or -1 if it's not an array + + + + + a #GITypeInfo + + + + + + Obtain the array length of the type. The type tag must be a +#GI_TYPE_TAG_ARRAY or -1 will returned. + + + the array length, or -1 if the type is not an array + + + + + a #GITypeInfo + + + + + + Obtain the array type for this type. See #GIArrayType for a list of +possible values. If the type tag of this type is not array, -1 will be +returned. + + + the array type or -1 + + + + + a #GITypeInfo + + + + + + For types which have #GI_TYPE_TAG_INTERFACE such as GObjects and boxed values, +this function returns full information about the referenced type. You can then +inspect the type of the returned #GIBaseInfo to further query whether it is +a concrete GObject, a GInterface, a structure, etc. using g_base_info_get_type(). + + + the #GIBaseInfo, or %NULL. Free it with +g_base_info_unref() when done. + + + + + a #GITypeInfo + + + + + + Obtain the parameter type @n. + + + the param type info + + + + + a #GITypeInfo + + + + index of the parameter + + + + + + Obtain the type tag for the type. See #GITypeTag for a list +of type tags. + + + the type tag + + + + + a #GITypeInfo + + + + + + Obtain if the type is passed as a reference. + +Note that the types of %GI_DIRECTION_OUT and %GI_DIRECTION_INOUT parameters +will only be pointers if the underlying type being transferred is a pointer +(i.e. only if the type of the C function’s formal parameter is a pointer to a +pointer). + + + %TRUE if it is a pointer + + + + + a #GITypeInfo + + + + + + Obtain if the last element of the array is %NULL. The type tag must be a +#GI_TYPE_TAG_ARRAY or %FALSE will returned. + + + %TRUE if zero terminated + + + + + a #GITypeInfo + + + + + + Obtain a string representation of @type + + + the string + + + + + the type_tag + + + + + + Obtain the type information for method named @name. + + + the #GIFunctionInfo, free it with g_base_info_unref() +when done. + + + + + a #GIUnionInfo + + + + a method name + + + + + + Obtain the required alignment of the union. + + + required alignment in bytes + + + + + a #GIUnionInfo + + + + + + Obtain discriminator value assigned for n-th union field, i.e. n-th +union field is the active one if discriminator contains this +constant. + + + the #GIConstantInfo, free it with g_base_info_unref() +when done. + + + + + a #GIUnionInfo + + + + a union field index + + + + + + Returns offset of the discriminator field in the structure. + + + offset in bytes of the discriminator + + + + + a #GIUnionInfo + + + + + + Obtain the type information of the union discriminator. + + + the #GITypeInfo, free it with g_base_info_unref() +when done. + + + + + a #GIUnionInfo + + + + + + Obtain the type information for field with specified index. + + + the #GIFieldInfo, free it with g_base_info_unref() +when done. + + + + + a #GIUnionInfo + + + + a field index + + + + + + Obtain the type information for method with specified index. + + + the #GIFunctionInfo, free it with g_base_info_unref() +when done. + + + + + a #GIUnionInfo + + + + a method index + + + + + + Obtain the number of fields this union has. + + + number of fields + + + + + a #GIUnionInfo + + + + + + Obtain the number of methods this union has. + + + number of methods + + + + + a #GIUnionInfo + + + + + + Obtain the total size of the union. + + + size of the union in bytes + + + + + a #GIUnionInfo + + + + + + Return true if this union contains discriminator field. + + + %TRUE if this is a discriminated union, %FALSE otherwise + + + + + a #GIUnionInfo + + + + + + Obtain the enumeration value of the #GIValueInfo. + + + the enumeration value. This will always be representable + as a 32-bit signed or unsigned value. The use of gint64 as the + return type is to allow both. + + + + + a #GIValueInfo + + + + + + This method will look up where inside the type struct of @implementor_gtype +is the implementation for @info. + + + address to a function or %NULL if an error happened + + + + + a #GIVFuncInfo + + + + #GType implementing this virtual function + + + + + + Obtain the flags for this virtual function info. See #GIVFuncInfoFlags for +more information about possible flag values. + + + the flags + + + + + a #GIVFuncInfo + + + + + + If this virtual function has an associated invoker method, this +method will return it. An invoker method is a C entry point. + +Not all virtuals will have invokers. + + + the #GIVFuncInfo or %NULL. Free it with +g_base_info_unref() when done. + + + + + a #GIVFuncInfo + + + + + + Obtain the offset of the function pointer in the class struct. The value +0xFFFF indicates that the struct offset is unknown. + + + the struct offset or 0xFFFF if it's unknown + + + + + a #GIVFuncInfo + + + + + + Obtain the signal for the virtual function if one is set. +The signal comes from the object or interface to which +this virtual function belongs. + + + the signal or %NULL if none set + + + + + a #GIVFuncInfo + + + + + + Invokes the function described in @info with the given +arguments. Note that inout parameters must appear in both +argument lists. + + + %TRUE if the function has been invoked, %FALSE if an + error occurred. + + + + + a #GIVFuncInfo describing the virtual function to invoke + + + + #GType of the type that implements this virtual function + + + + an array of #GIArgument<!-- -->s, one for each in + parameter of @info. If there are no in parameter, @in_args + can be %NULL + + + + + + the length of the @in_args array + + + + an array of #GIArgument<!-- -->s, one for each out + parameter of @info. If there are no out parameters, @out_args + may be %NULL + + + + + + the length of the @out_args array + + + + return location for the return value of the + function. If the function returns void, @return_value may be + %NULL + + + + + + diff --git a/gir-files/GL-1.0.gir b/gir-files/GL-1.0.gir new file mode 100644 index 0000000..c2d3a6c --- /dev/null +++ b/gir-files/GL-1.0.gir @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/GLib-2.0.gir b/gir-files/GLib-2.0.gir new file mode 100644 index 0000000..3d7e51e --- /dev/null +++ b/gir-files/GLib-2.0.gir @@ -0,0 +1,51313 @@ + + + + + + + + Integer representing a day of the month; between 1 and 31. +#G_DATE_BAD_DAY represents an invalid day of the month. + + + + + Integer representing a year; #G_DATE_BAD_YEAR is the invalid +value. The year must be 1 or higher; negative (BC) years are not +allowed. The year is represented with four digits. + + + + + 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. + + + + + 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 g_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: +|[<!-- language="C" --> + char buf[G_ASCII_DTOSTR_BUF_SIZE]; + + fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); +]| + + + + + + + + + + + + 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. + + + the #GArray + + + + + + + a #GArray + + + + + + 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 +get 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. If @target exists multiple times in @array, the index +of the first instance is returned. 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 search an element in a #GArray: +|[<!-- language="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. + + + + + a #GArray. + + + + + + a pointer to the item to look up. + + + + A #GCompareFunc used to locate @target. + + + + return location + for the index of the element, if found. + + + + + + Create 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. + + + A copy of @array. + + + + + + + A #GArray. + + + + + + + + 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_seg 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 g_array_ref() and g_array_unref() +functions. + + + the element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free(). + + + + + a #GArray + + + + + + if %TRUE the actual element data is freed as well + + + + + + Gets the size of the elements in @array. + + + Size of each element, in bytes + + + + + A #GArray + + + + + + + + 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. + +@data may be %NULL if (and only if) @len is zero. If @len is zero, this +function is a no-op. + + + the #GArray + + + + + + + a #GArray + + + + + + 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 + + + + + + + %TRUE if the array should have an extra element at + the end which is set to 0 + + + + %TRUE if #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 g_array_append_vals() since the +existing elements in the array have to be moved to make space for +the new elements. + + + the #GArray + + + + + + + a #GArray + + + + + + 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 + + + + + + + A #GArray + + + + + + + + Removes the element at the given index from a #GArray. The following +elements are moved down one place. + + + the #GArray + + + + + + + a #GArray + + + + + + 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 +g_array_remove_index(). + + + the #GArray + + + + + + + a @GArray + + + + + + 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 + + + + + + + a @GArray + + + + + + 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 #GDestroyNotify +functions, @clear_func is expected to clear the contents of +the array element it is given, but not free the element itself. + + + + + + + A #GArray + + + + + + 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 + + + + + + + a #GArray + + + + + + 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 + + + + + + + %TRUE if the array should have an extra element at + the end with all bits cleared + + + + %TRUE if all bits in the array should be cleared to 0 on + allocation + + + + size of each element in the array + + + + 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. + + + + + + + a #GArray + + + + + + comparison function + + + + + + Like g_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. + + + + + + + a #GArray + + + + + + comparison function + + + + data to pass to @compare_func + + + + + + 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 #GArray + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The GAsyncQueue struct is 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. @data must not be %NULL. + + + + + + + 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(), 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. @data must not be %NULL. + +This function must be called while holding the @queue's lock. + + + + + + + a #GAsyncQueue + + + + @data to push into 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. + + + + + The `GBookmarkFile` structure contains only +private data and should not be directly accessed. + + + 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 + + + + + + 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. + + + a timestamp + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Gets the registration information of @app_name for the bookmark for +@uri. See g_bookmark_file_set_app_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. + + + a timestamp + + + + + 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. + + + a timestamp. + + + + + 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. + + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a timestamp or -1 to use the current time + + + + + + 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_app_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. + + + %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 @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(). + + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a timestamp or -1 to use the current time + + + + + + 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_app_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 timestamp or -1 to use the current time + + + + + + 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 + + + + + + + + + + + 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 + + + + + + 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 #GByteArray + + + + + + 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 element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free(). + + + + + a #GByteArray + + + + + + if %TRUE the actual byte data is freed as well + + + + + + Transfers the data from the #GByteArray into a new immutable #GBytes. + +The #GByteArray is freed unless the reference count of @array is greater +than one, the #GByteArray wrapper is preserved but the size of @array +will be set to zero. + +This is identical to using g_bytes_new_take() and g_byte_array_free() +together. + + + a new immutable #GBytes representing same + byte data that was in the array + + + + + a #GByteArray + + + + + + + + Creates a new #GByteArray with a reference count of 1. + + + the new #GByteArray + + + + + + + Create byte array containing the data. The data will be owned by the array +and will be freed with g_free(), i.e. it could be allocated using g_strdup(). + + + a new #GByteArray + + + + + + + byte data for the array + + + + + + 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 #GByteArray + + + + + + 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 #GByteArray + + + + + + + + Removes the byte at the given index from a #GByteArray. +The following bytes are moved down one place. + + + the #GByteArray + + + + + + + a #GByteArray + + + + + + 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 g_byte_array_remove_index(). + + + the #GByteArray + + + + + + + a #GByteArray + + + + + + 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 @GByteArray + + + + + + 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 #GByteArray + + + + + + 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 + + + + + + + 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 #GByteArray + + + + + + comparison function + + + + + + Like g_byte_array_sort(), but the comparison function takes an extra +user data argument. + + + + + + + a #GByteArray + + + + + + comparison function + + + + data to pass to @compare_func + + + + + + 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 #GByteArray + + + + + + + + + A simple refcounted 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 g_malloc(), from memory slices, from a #GMappedFile or +memory from other allocators. + +#GBytes work well as keys in #GHashTable. Use g_bytes_equal() and +g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full(). +#GBytes can also be used as keys in a #GTree by passing the g_bytes_compare() +function to g_tree_new(). + +The data pointed to by this bytes must not be modified. For a mutable +array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a +mutable array for a #GBytes sequence. To create an immutable #GBytes from +a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. + + + Creates a new #GBytes from @data. + +@data is copied. If @size is 0, @data may be %NULL. + + + a new #GBytes + + + + + + the data to be used for the bytes + + + + + + the size of @data + + + + + + Creates a new #GBytes from static data. + +@data must be static (ie: never modified or freed). It may be %NULL if @size +is 0. + + + a new #GBytes + + + + + + the data to be used for the bytes + + + + + + the size of @data + + + + + + Creates a new #GBytes from @data. + +After this call, @data belongs to the bytes and may no longer be +modified by the caller. g_free() will be called on @data when the +bytes is no longer in use. Because of this @data must have been created by +a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many +functions that wrap these calls (such as g_new(), g_strdup(), etc). + +For creating #GBytes with memory from other allocators, see +g_bytes_new_with_free_func(). + +@data may be %NULL if @size is 0. + + + a new #GBytes + + + + + + the data to be used for the bytes + + + + + + the size of @data + + + + + + Creates a #GBytes 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 #GBytes + + + + + + 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 #GBytes 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 #GBytes + + + + a pointer to a #GBytes to compare with @bytes1 + + + + + + Compares the two #GBytes values being pointed to and returns +%TRUE if they are equal. + +This function can be passed to g_hash_table_new() as the @key_equal_func +parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. + + + %TRUE if the two keys match. + + + + + a pointer to a #GBytes + + + + a pointer to a #GBytes to compare with @bytes1 + + + + + + Get the byte data in the #GBytes. 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, or %NULL + + + + + + + a #GBytes + + + + location to return size of byte data + + + + + + Get the size of the byte data in the #GBytes. + +This function will always return the same value for a given #GBytes. + + + the size + + + + + a #GBytes + + + + + + Creates an integer hash code for the byte data in the #GBytes. + +This function can be passed to g_hash_table_new() as the @key_hash_func +parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. + + + a hash value corresponding to the key. + + + + + a pointer to a #GBytes key + + + + + + Creates a #GBytes 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 #GBytes + + + + + a #GBytes + + + + offset which subsection starts at + + + + length of subsection + + + + + + Increase the reference count on @bytes. + + + the #GBytes + + + + + a #GBytes + + + + + + Releases a reference on @bytes. This may result in the bytes being +freed. If @bytes is %NULL, it will return immediately. + + + + + + + a #GBytes + + + + + + Unreferences the bytes, and returns a new mutable #GByteArray 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 +g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all +other cases the data is copied. + + + a new mutable #GByteArray containing the same byte data + + + + + + + a #GBytes + + + + + + 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 g_bytes_new(), +g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the +data is copied. + + + a pointer to the same byte data, which should be + freed with g_free() + + + + + + + a #GBytes + + + + location to place the length of the returned data + + + + + + + Checks the version of the GLib library that is being compiled +against. 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. + + + + + An opaque structure representing a checksumming operation. +To create a new GChecksum, use g_checksum_new(). To free +a GChecksum, use g_checksum_free(). + + + 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 an 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 @status, see the documentation +for g_spawn_check_exit_status(). + + + + + + + the process id of the child process + + + + Status information about the child process, encoded + in a platform-specific manner + + + + user data passed to g_child_watch_add() + + + + + + Specifies the type of function passed to g_clear_handle_id(). +The implementation is expected to free the resource identified +by @handle_id; for instance, if @handle_id is a #GSource ID, +g_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 + + + + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + + 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. + + + + + 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 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark +functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it +is meant to be portable across different compilers and must be placed +before the function declaration. + +|[<!-- language="C" -- +G_DEPRECATED_FOR(my_replacement) +int my_mistake (void); +]| + + + + the name of the function that this function was deprecated for + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + The #GData struct is an opaque data structure to represent a +[Keyed Data List][glib-Keyed-Data-Lists]. It should only be +accessed via the following functions. + + + + 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(). + + + + + + Represents a day between January 1, Year 1 and a few thousand years in +the future. None of its members should be accessed directly. + +If the #GDate-struct is obtained from g_date_new(), it will be safe +to mutate but invalid and thus not safe for calendrical computations. + +If it's declared on the stack, it will contain garbage so must be +initialized with g_date_clear(). g_date_clear() makes the date invalid +but sane. An invalid date doesn't represent a day, it's "empty." A date +becomes valid after you set it to a Julian day or you set a day, month, +and year. + + + 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 day of the day-month-year representation of the date, + as a number between 1 and 12 + + + + the day of the day-month-year representation of the date + + + + Allocates a #GDate and initializes +it to a sane 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 + + + + + Like g_date_new(), but also sets the value of the date. Assuming the +day-month-year triplet you pass in represents an existing day, the +returned date will be valid. + + + a newly-allocated #GDate initialized with @day, @month, and @year + + + + + day of the month + + + + month of the year + + + + year + + + + + + Like g_date_new(), but also sets the value of the date. Assuming the +Julian day number you pass in is valid (greater than 0, less than an +unreasonably large number), the returned date will be 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 sane 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 + + + + + + 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][setlocale] 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 sane 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 + + + + + + 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][setlocale]-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 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 an opaque structure whose members +cannot be accessed directly. + + + 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. + +<sep> is the separator and can be either 'T', 't' or ' '. + +<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 #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 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 the system clock is set to +truly insane values (or 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(). + + + + + 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(). + + + + + 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 that should be freed with + g_date_time_unref(). + + + + + 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(). + + + + + 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(). + + + + + 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(). + + + + + 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(). + + + + + 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(). + + + + + 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(). + + + + + a #GDateTime + + + + the number of years + + + + + + 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 + + + + + + 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. + +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) +- \%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 blank +- \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); + single digits are preceded by a blank +- \%m: the month as a decimal number (range 01 to 12) +- \%M: the minute as a decimal number (range 00 to 59) +- \%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". +- \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for + the current locale +- \%r: the time in a.m. or p.m. notation +- \%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. + +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 + + + 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. + + + 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. + + + + + + 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 + + + + + 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). + +You should release the return value by calling g_date_time_unref() +when you are done with it. + + + a new #GDateTime, 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 + + + + + + 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 + + + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + Hashes @datetime into a #guint, suitable for use within #GHashTable. + + + a #guint containing the hash + + + + + 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. + + + Closes the directory and deallocates all related resources. + + + + + + + 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() + + + + + + 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() + + + + + + 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 + + + + + + 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. + + + + + + + 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 + + + + + + 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 + + + + + + + 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. + + + + 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, ‘Mb’ rather than ‘MB’. + + + + 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() + + + + + + This is the platform dependent conversion specifier for scanning and +printing values of type #gint16. It is a string literal, but doesn't +include the percent-sign, such that you can add precision and length +modifiers between percent-sign and conversion specifier. + +|[<!-- language="C" --> +gint16 in; +gint32 out; +sscanf ("42", "%" G_GINT16_FORMAT, &in) +out = in * 1000; +g_print ("%" G_GINT32_FORMAT, out); +]| + + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gint16 or #guint16. It +is a string literal, but doesn't include the percent-sign, such +that you can add precision and length modifiers between percent-sign +and conversion specifier and append a conversion specifier. + +The following example prints "0x7b"; +|[<!-- language="C" --> +gint16 value = 123; +g_print ("%#" G_GINT16_MODIFIER "x", value); +]| + + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gint32. See also #G_GINT16_FORMAT. + + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gint32 or #guint32. It +is a string literal. See also #G_GINT16_MODIFIER. + + + + + This macro is used to insert 64-bit integer literals +into the source code. + + + + a literal integer value, e.g. 0x1d636b02300a7aa7 + + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gint64. See also #G_GINT16_FORMAT. + +Some platforms do not support scanning and printing 64-bit integers, +even though the types are supported. On such platforms %G_GINT64_FORMAT +is not defined. Note that scanf() may not support 64-bit integers, even +if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() +is not recommended for parsing anyway; consider using g_ascii_strtoull() +instead. + + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gint64 or #guint64. +It is a string literal. + +Some platforms do not support printing 64-bit integers, even +though the types are supported. On such platforms %G_GINT64_MODIFIER +is not defined. + + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gintptr. + + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gintptr or #guintptr. +It is a string literal. + + + + + 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 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) + + + + + This macro is used to insert #goffset 64-bit integer literals +into the source code. + +See also #G_GINT64_CONSTANT. + + + + a literal integer value, e.g. 0x1d636b02300a7aa7 + + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gsize. See also #G_GINT16_FORMAT. + + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gsize. It +is a string literal. + + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gssize. See also #G_GINT16_FORMAT. + + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gssize. It +is a string literal. + + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #guint16. See also #G_GINT16_FORMAT + + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #guint32. See also #G_GINT16_FORMAT. + + + + + This macro is used to insert 64-bit unsigned integer +literals into the source code. + + + + a literal integer value, e.g. 0x1d636b02300a7aa7U + + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #guint64. See also #G_GINT16_FORMAT. + +Some platforms do not support scanning and printing 64-bit integers, +even though the types are supported. On such platforms %G_GUINT64_FORMAT +is not defined. Note that scanf() may not support 64-bit integers, even +if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() +is not recommended for parsing anyway; consider using g_ascii_strtoull() +instead. + + + + + This is the platform dependent conversion specifier +for scanning and printing values of type #guintptr. + + + + + + + + + + + + + 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 +g_hash_table_foreach_remove(). It is called with each key/value +pair, together with the @user_data parameter passed to +g_hash_table_foreach_remove(). It should return %TRUE if the +key/value pair should be removed from the #GHashTable. + + + %TRUE if the key/value pair should be removed from the + #GHashTable + + + + + a key + + + + the value associated with the key + + + + user data passed to g_hash_table_remove() + + + + + + 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 +vulerable 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][glib-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. + +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(). + +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 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 + + + + + + + + + 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. + + + + + + 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 + + + + + + + + + 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(). + +You can pass %NULL for @lookup_key, 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 + + + + + + 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(). + + + + + + + + + + + + + + + + + + + + + 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. +|[<!-- 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 + + + + + + + An opaque structure representing a HMAC operation. +To create a new GHmac, use g_hmac_new(). To free +a GHmac, use g_hmac_unref(). + + + 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 an 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 + + + + + + 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 + + + + + + + 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 + + + A mask covering all bits reserved for + hook flags; see %G_HOOK_FLAG_USER_SHIFT + + + + 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. + + + 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. + + + + + A data structure representing an IO Channel. The fields should be +considered private and should only be accessed with the following +functions. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + 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 + complelely 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(). + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stati 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](http://freedesktop.org/Standards/desktop-entry-spec). +Consult the specification for more +details about the meanings of the keys below. + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list +giving the available application actions. + + + + + A key under #G_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 #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the tooltip for the desktop entry. + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true +if the application is D-Bus activatable. + + + + + A key under #G_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 #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the generic name of the desktop entry. + + + + + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the desktop entry has been deleted by the user. + + + + + A key under #G_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 #G_KEY_FILE_DESKTOP_GROUP, whose value is a list +of strings giving the MIME types supported by this desktop entry. + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the specific name of the desktop entry. + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of +strings identifying the environments that should not display the +desktop entry. + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the desktop entry should be shown in menus. + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of +strings identifying the environments that should display the +desktop entry. + + + + + A key under #G_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 #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the application supports the +[Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). + + + + + A key under #G_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 with +older applications. + + + + + A key under #G_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 #G_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 #G_KEY_FILE_DESKTOP_GROUP, whose value is a string +giving the type of the desktop entry. Usually +#G_KEY_FILE_DESKTOP_TYPE_APPLICATION, +#G_KEY_FILE_DESKTOP_TYPE_LINK, or +#G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. + + + + + A key under #G_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 #G_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 #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing applications. + + + + + The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing directories. + + + + + The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing links to documents. + + + + + The GKeyFile struct contains only private data +and should not be accessed directly. + + + Creates a new empty #GKeyFile object. Use +g_key_file_load_from_file(), g_key_file_load_from_data(), +g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to +read an existing key file. + + + an empty #GKeyFile. + + + + + 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 #GKeyFile + + + + + + Returns the value associated with @key under @group_name as a +boolean. + +If @key cannot be found then %FALSE is returned and @error is set +to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value +associated with @key cannot be interpreted as a boolean then %FALSE +is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + the value associated with the key as a boolean, + or %FALSE if the key was not found or could not be parsed. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Returns the values associated with @key under @group_name as +booleans. + +If @key cannot be found then %NULL is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated +with @key cannot be interpreted as booleans then %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + + 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 g_free() when no longer needed. + + + + + + + a #GKeyFile + + + + 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 g_free() + + + + + a #GKeyFile + + + + a group name, or %NULL + + + + a key + + + + + + Returns the value associated with @key under @group_name as a +double. If @group_name is %NULL, the start_group is used. + +If @key cannot be found then 0.0 is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated +with @key cannot be interpreted as a double then 0.0 is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + the value associated with the key as a double, or + 0.0 if the key was not found or could not be parsed. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Returns the values associated with @key under @group_name as +doubles. + +If @key cannot be found then %NULL is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated +with @key cannot be interpreted as doubles then %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + + 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 g_free() when no longer needed. + + + + + + + a #GKeyFile + + + + 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 g_strfreev() to free it. + + + + + + + a #GKeyFile + + + + return location for the number of returned groups, or %NULL + + + + + + Returns the value associated with @key under @group_name as a signed +64-bit integer. This is similar to g_key_file_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 non-%NULL #GKeyFile + + + + a non-%NULL group name + + + + a non-%NULL key + + + + + + Returns the value associated with @key under @group_name as an +integer. + +If @key cannot be found then 0 is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated +with @key cannot be interpreted as an integer, or is out of range +for a #gint, then 0 is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + the value associated with the key as an integer, or + 0 if the key was not found or could not be parsed. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Returns the values associated with @key under @group_name as +integers. + +If @key cannot be found then %NULL is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated +with @key cannot be interpreted as integers, or are out of range for +#gint, then %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + + 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 g_free() when no longer needed. + + + + + + + a #GKeyFile + + + + 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. In the event that the @group_name cannot +be found, %NULL is returned and @error is set to +#G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + + + a newly-allocated %NULL-terminated array of strings. + Use g_strfreev() to free it. + + + + + + + a #GKeyFile + + + + a group name + + + + return location for the number of keys returned, or %NULL + + + + + + Returns the actual locale which the result of +g_key_file_get_locale_string() or g_key_file_get_locale_string_list() +came from. + +If calling g_key_file_get_locale_string() or +g_key_file_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 #GKeyFile + + + + a group name + + + + a key + + + + a locale identifier or %NULL + + + + + + Returns the value associated with @key under @group_name +translated in the given @locale if available. 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 #GKeyFile, it must be loaded with +%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. + +If @key cannot be found then %NULL is returned and @error is set +to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. 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 #GKeyFile + + + + a group name + + + + a key + + + + a locale identifier or %NULL + + + + + + Returns the values associated with @key under @group_name +translated in the given @locale if available. 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 #GKeyFile, it must be loaded with +%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. + +If @key cannot be found then %NULL is returned and @error is set +to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. 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 g_strfreev(). + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a locale identifier or %NULL + + + + return location for the number of returned strings or %NULL + + + + + + Returns the name of the start group of the file. + + + The start group of the key file. + + + + + a #GKeyFile + + + + + + Returns the string value associated with @key under @group_name. +Unlike g_key_file_get_value(), this function handles escape sequences +like \s. + +In the event the key cannot be found, %NULL is returned and +@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the +event that the @group_name cannot be found, %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + + + a newly allocated string or %NULL if the specified + key cannot be found. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Returns the values associated with @key under @group_name. + +In the event the key cannot be found, %NULL is returned and +@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the +event that the @group_name cannot be found, %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + + + + a %NULL-terminated string array or %NULL if the specified + key cannot be found. The array should be freed with g_strfreev(). + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + return location for the number of returned strings, or %NULL + + + + + + Returns the value associated with @key under @group_name as an unsigned +64-bit integer. This is similar to g_key_file_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 non-%NULL #GKeyFile + + + + a non-%NULL group name + + + + a non-%NULL key + + + + + + Returns the raw value associated with @key under @group_name. +Use g_key_file_get_string() to retrieve an unescaped UTF-8 string. + +In the event the key cannot be found, %NULL is returned and +@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the +event that the @group_name cannot be found, %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + + + a newly allocated string or %NULL if the specified + key cannot be found. + + + + + a #GKeyFile + + + + 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 #GKeyFile + + + + 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 #GError strictly; +the return value both carries meaning and signals an error. To use +this function, you must pass a #GError pointer in @error, and check +whether it is not %NULL to see if an error occurred. + +Language bindings should use g_key_file_get_value() to test whether +or not a key exists. + + + %TRUE if @key is a part of @group_name, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name + + + + a key name + + + + + + Loads a key file from the data in @bytes into an empty #GKeyFile structure. +If the object cannot be created then %error is set to a #GKeyFileError. + + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + an empty #GKeyFile struct + + + + a #GBytes + + + + flags from #GKeyFileFlags + + + + + + Loads a key file from memory into an empty #GKeyFile structure. +If the object cannot be created then %error is set to a #GKeyFileError. + + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + an empty #GKeyFile struct + + + + key file loaded in memory + + + + the length of @data in bytes (or (gsize)-1 if data is nul-terminated) + + + + flags from #GKeyFileFlags + + + + + + This function looks for a key file named @file in the paths +returned from g_get_user_data_dir() and g_get_system_data_dirs(), +loads the file into @key_file and returns the file's full path in +@full_path. If the file could not be loaded then an %error is +set to either a #GFileError or #GKeyFileError. + + + %TRUE if a key file could be loaded, %FALSE othewise + + + + + an empty #GKeyFile 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 + + + + flags from #GKeyFileFlags + + + + + + This function 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. + +If the file could not be found in any of the @search_dirs, +%G_KEY_FILE_ERROR_NOT_FOUND is returned. If +the file is found but the OS returns an error when opening or reading the +file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a +%G_KEY_FILE_ERROR is returned. + + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + an empty #GKeyFile 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 + + + + flags from #GKeyFileFlags + + + + + + Loads a key file into an empty #GKeyFile structure. + +If the OS returns an error when opening or reading the file, a +%G_FILE_ERROR is returned. If there is a problem parsing the file, a +%G_KEY_FILE_ERROR is returned. + +This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the +@file is not found, %G_FILE_ERROR_NOENT is returned. + + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + an empty #GKeyFile struct + + + + the path of a filename to load, in the GLib filename encoding + + + + flags from #GKeyFileFlags + + + + + + Increases the reference count of @key_file. + + + the same @key_file. + + + + + a #GKeyFile + + + + + + 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 #GKeyFile + + + + a group name, or %NULL + + + + a key + + + + + + Removes the specified group, @group_name, +from the key file. + + + %TRUE if the group was removed, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name + + + + + + Removes @key in @group_name from the key file. + + + %TRUE if the key was removed, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name + + + + a key name to remove + + + + + + Writes the contents of @key_file to @filename using +g_file_set_contents(). + +This function can fail for any of the reasons that +g_file_set_contents() may fail. + + + %TRUE if successful, else %FALSE with @error set + + + + + a #GKeyFile + + + + 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 #GKeyFile + + + + 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. +If @group_name is %NULL, the start_group is used. + + + + + + + a #GKeyFile + + + + 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. + +Note that this function prepends a '#' comment marker to +each line of @comment. + + + %TRUE if the comment was written, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name, or %NULL + + + + a key + + + + a comment + + + + + + Associates a new double value with @key under @group_name. +If @key cannot be found then it is created. + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an double value + + + + + + Associates a list of double values with @key under +@group_name. If @key cannot be found then it is created. + + + + + + + a #GKeyFile + + + + 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 #GKeyFile + + + + 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 #GKeyFile + + + + 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 #GKeyFile + + + + 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 #GKeyFile + + + + 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. + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a locale identifier + + + + a string + + + + + + Associates a list of string values for @key and @locale under +@group_name. If the translation for @key cannot be found then +it is created. + + + + + + + a #GKeyFile + + + + 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 g_key_file_set_value(), this function handles characters +that need escaping, such as newlines. + + + + + + + a #GKeyFile + + + + 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 #GKeyFile + + + + 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 #GKeyFile + + + + 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 +g_key_file_set_string(). + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a string + + + + + + This function outputs @key_file as a string. + +Note that this function never reports an error, +so it is safe to pass %NULL as @error. + + + a newly allocated string holding + the contents of the #GKeyFile + + + + + a #GKeyFile + + + + return location for the length of the + returned string, or %NULL + + + + + + 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 #GKeyFile + + + + + + + + + + + + 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][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][glib-Type-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. + + + + + + + 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). + + + + + + + a pointer to 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, g_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. + +This is not used if structured logging is enabled; see +[Using Structured Logging][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 g_log_set_handler() + + + + + + Flags specifying the level of log messages. + +It is possible to change how GLib treats messages of the various +levels using g_log_set_handler() and g_log_set_fatal_mask(). + + + internal flag + + + internal flag + + + log level for errors, see g_error(). + This level is also used for messages produced by g_assert(). + + + log level for critical warning messages, see + g_critical(). + This level is also used for messages produced by g_return_if_fail() + and g_return_val_if_fail(). + + + log level for warnings, see g_warning() + + + log level for messages, see g_message() + + + log level for informational messages, see g_info() + + + log level for debug messages, see g_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 maximum value which can be held in a #gint16. + + + + + The maximum value which can be held in a #gint32. + + + + + The maximum value which can be held in a #gint64. + + + + + The maximum value which can be held in a #gint8. + + + + + The maximum value which can be held in a #guint16. + + + + + The maximum value which can be held in a #guint32. + + + + + The maximum value which can be held in a #guint64. + + + + + The maximum value which can be held in a #guint8. + + + + + 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. + + + + + + + + + The `GMainContext` struct is an opaque data +type representing a set of sources to be handled in a main loop. + + + Creates a new #GMainContext structure. + + + the new #GMainContext + + + + + 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 g_main_context_release() +is called as many times as g_main_context_acquire(). + +You must be the owner of a context before you +can call g_main_context_prepare(), g_main_context_query(), +g_main_context_check(), g_main_context_dispatch(). + + + %TRUE if the operation succeeded, and + this thread is now the owner of @context. + + + + + a #GMainContext + + + + + + 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 #GMainContext (or %NULL for the default context) + + + + a #GPollFD 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 g_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 must have successfully acquired the context with +g_main_context_acquire() before you may call this function. + + + %TRUE if some sources are ready to be dispatched. + + + + + a #GMainContext + + + + the maximum numerical priority of sources to check + + + + array of #GPollFD's that was passed to + the last call to g_main_context_query() + + + + + + return value of g_main_context_query() + + + + + + Dispatches all pending sources. + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function. + + + + + + + a #GMainContext + + + + + + 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 #GMainContext (if %NULL, the default context will be used). + + + + the @source_funcs passed to g_source_new(). + + + + the user data from the callback. + + + + + + Finds a #GSource 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 g_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 #GSource + + + + + a #GMainContext (if %NULL, the default context will be used) + + + + the source ID, as returned by g_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 #GMainContext + + + + the user_data for the callback. + + + + + + Gets the poll function set by g_main_context_set_poll_func(). + + + the poll function + + + + + a #GMainContext + + + + + + 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 g_main_context_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 g_main_context_acquire() succeeds, then +@function is called and g_main_context_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 #G_PRIORITY_DEFAULT +priority. If you want a different priority, use +g_main_context_invoke_full(). + +Note that, as with normal idle functions, @function should probably +return %FALSE. If it returns %TRUE, it will be continuously run in a +loop (and may prevent this call from returning). + + + + + + + a #GMainContext, or %NULL + + + + 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 g_main_context_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 #GDestroyNotify for @data. + +@notify should not assume that it is called from any particular +thread or with any particular context acquired. + + + + + + + a #GMainContext, or %NULL + + + + 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, or %NULL. + + + + + + Determines whether this thread holds the (recursive) +ownership of this #GMainContext. 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. + + + + + a #GMainContext + + + + + + 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 +sources are not waited to become ready, only those highest priority +events sources will be dispatched (if any), that are ready at this +given moment without further waiting. + +Note that even when @may_block is %TRUE, it is still possible for +g_main_context_iteration() to return %FALSE, since the wait may +be interrupted for other reasons than an event source becoming ready. + + + %TRUE if events were dispatched. + + + + + a #GMainContext (if %NULL, the default 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. + + + + + a #GMainContext (if %NULL, the default context will be used) + + + + + + Pops @context off the thread-default context stack (verifying that +it was on the top of the stack). + + + + + + + a #GMainContext object, or %NULL + + + + + + Prepares to poll sources within a main loop. The resulting information +for polling is determined by calling g_main_context_query (). + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function. + + + %TRUE if some source is ready to be dispatched + prior to polling. + + + + + a #GMainContext + + + + 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]-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 context in the main thread. Note that calling this function +changes the context returned by g_main_context_get_thread_default(), +not the one returned by g_main_context_default(), so it does not affect +the context used by functions like g_idle_add(). + +Normally you would call this function shortly after creating a new +thread, passing it a #GMainContext which will be run by a +#GMainLoop 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 g_main_context_pop_thread_default(), assuming you want the +new #GMainContext 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 #GMainContext inside a +g_main_context_push_thread_default() / g_main_context_pop_thread_default() +pair, otherwise threads that are re-used will end up never explicitly +releasing the #GMainContext 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 +g_main_context_push_thread_default() / +g_main_context_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. Eg, +see g_file_supports_thread_contexts(). + + + + + + + a #GMainContext, or %NULL for the global default context + + + + + + Determines information necessary to poll this main loop. + +You must have successfully acquired the context with +g_main_context_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 #GMainContext + + + + maximum priority source to check + + + + location to store timeout to be used in polling + + + + location to + store #GPollFD records that need to be polled. + + + + + + length of @fds. + + + + + + Increases the reference count on a #GMainContext object by one. + + + the @context that was passed in (since 2.6) + + + + + a #GMainContext + + + + + + Releases ownership of a context previously acquired by this thread +with g_main_context_acquire(). If the context was acquired multiple +times, the ownership will be released only when g_main_context_release() +is called as many times as it was acquired. + + + + + + + a #GMainContext + + + + + + Removes file descriptor from the set of file descriptors to be +polled for a particular context. + + + + + + + a #GMainContext + + + + a #GPollFD descriptor previously added with g_main_context_add_poll() + + + + + + Sets the function to use to handle polling of file descriptors. It +will be used instead of the poll() 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 #GMainContext + + + + the function to call to poll all file descriptors + + + + + + Decreases the reference count on a #GMainContext object by one. If +the result is zero, free the context and free all associated memory. + + + + + + + a #GMainContext + + + + + + Tries to become the owner of the specified context, +as with g_main_context_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 g_main_context_is_owner() and separate locking instead. + + + %TRUE if the operation succeeded, and + this thread is now the owner of @context. + + + + + a #GMainContext + + + + a condition variable + + + + a mutex, currently held + + + + + + If @context is currently blocking in g_main_context_iteration() +waiting for a source to become ready, cause it to stop blocking +and return. Otherwise, cause the next invocation of +g_main_context_iteration() to return without blocking. + +This API is useful for low-level control over #GMainContext; for +example, integrating it with main loop implementations such as +#GMainLoop. + +Another related use for this function is when implementing a main +loop with a termination condition, computed from multiple threads: + +|[<!-- language="C" --> + #define NUM_TASKS 10 + static volatile gint tasks_remaining = NUM_TASKS; + ... + + while (g_atomic_int_get (&tasks_remaining) != 0) + g_main_context_iteration (NULL, TRUE); +]| + +Then in a thread: +|[<!-- language="C" --> + perform_work(); + + if (g_atomic_int_dec_and_test (&tasks_remaining)) + g_main_context_wakeup (NULL); +]| + + + + + + + a #GMainContext + + + + + + 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 +g_main_context_get_thread_default(). + + + the global default main context. + + + + + Gets the thread-default #GMainContext 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 +g_main_context_ref_thread_default() to get a #GMainContext to add +their #GSources 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 +g_main_context_ref_thread_default() instead. + + + the thread-default #GMainContext, or +%NULL if the thread-default context is the global default context. + + + + + Gets the thread-default #GMainContext for this thread, as with +g_main_context_get_thread_default(), but also adds a reference to +it with g_main_context_ref(). In addition, unlike +g_main_context_get_thread_default(), if the thread-default context +is the global default context, this will return that #GMainContext +(with a ref added to it) rather than returning %NULL. + + + the thread-default #GMainContext. Unref + with g_main_context_unref() when you are done with it. + + + + + + The `GMainLoop` struct is an opaque data type +representing the main event loop of a GLib or GTK+ application. + + + Creates a new #GMainLoop structure. + + + a new #GMainLoop. + + + + + a #GMainContext (if %NULL, the default context will be used). + + + + set to %TRUE to indicate that the loop is running. This +is not very important since calling g_main_loop_run() will set this to +%TRUE anyway. + + + + + + Returns the #GMainContext of @loop. + + + the #GMainContext of @loop + + + + + a #GMainLoop. + + + + + + Checks to see if the main loop is currently being run via g_main_loop_run(). + + + %TRUE if the mainloop is currently being run. + + + + + a #GMainLoop. + + + + + + Stops a #GMainLoop from running. Any calls to g_main_loop_run() +for the loop will return. + +Note that sources that have already been dispatched when +g_main_loop_quit() is called will still be executed. + + + + + + + a #GMainLoop + + + + + + Increases the reference count on a #GMainLoop object by one. + + + @loop + + + + + a #GMainLoop + + + + + + Runs a main loop until g_main_loop_quit() is called on the loop. +If this is called for the thread of the loop's #GMainContext, +it will process events from the loop, otherwise it will +simply wait. + + + + + + + a #GMainLoop + + + + + + Decreases the reference count on a #GMainLoop object by one. If +the result is zero, free the loop and free all associated memory. + + + + + + + a #GMainLoop + + + + + + + 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 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 + + + + + + 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. + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + %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, or %NULL + + + + + + Retrieves the position in bytes of 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 @start_pos +and @end_pos are set to -1 and %TRUE 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 +position 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. + + + %TRUE if the position was fetched, %FALSE otherwise. If + the position cannot be fetched, @start_pos and @end_pos are left + unchanged + + + + + #GMatchInfo structure + + + + number of the sub expression + + + + pointer to location where to store + the start position, or %NULL + + + + pointer to location where to store + the end position, 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + +Sine: 2.32 + + + + + + + an initialized #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 + + + + + + + Returns %TRUE if a #GNode is a leaf node. + + + + a #GNode + + + + + Returns %TRUE if a #GNode is the root of a tree. + + + + a #GNode + + + + + 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][glib-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 +]| + + + %TRUE if the initialization section should be entered, + %FALSE and blocks otherwise + + + + + location of a static initializable variable + containing 0 + + + + + + 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. + + + + + + + location of a static initializable variable + containing 0 + + + + new non-0 value for *@value_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. + + + 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][setlocale] 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) + + + + + + + + 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...]` + + + + + + + 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: + - %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(). + + + + 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. Since: 2.42. + + + 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. + + + 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. + + + + 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. + + + 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() + + + + + + 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 g_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 +g_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 + + + + + A GPatternSpec struct is the 'compiled' form of a pattern. This +structure is opaque and its fields cannot be accessed directly. + + + 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 #GPatternSpec. + + + + + + + a #GPatternSpec + + + + + + Compiles a pattern to a #GPatternSpec. + + + a newly-allocated #GPatternSpec + + + + + a zero-terminated UTF-8 encoded string + + + + + + + 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 + + + + + + + Contains the public fields of a pointer array. + + + points to the array of pointers, which may be moved when the + array grows + + + + 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 #GPtrArray + + + + + + the pointer to add + + + + + + Makes a full (deep) copy of a #GPtrArray. + +@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. + +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 #GDestroyNotify for its elements as +@array. + + + a deep copy of the initial #GPtrArray. + + + + + + + #GPtrArray to duplicate + + + + + + a copy function used to copy every element in the array + + + + user data passed to the copy function @func, or %NULL + + + + + + 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 #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. + +If @func is %NULL, then only the pointers (and not what they are +pointing to) are copied to the new #GPtrArray. + + + + + + + a #GPtrArray. + + + + + + a #GPtrArray to add to the end of @array_to_extend. + + + + + + a copy function used to copy every element in the array + + + + user data passed to the copy function @func, or %NULL + + + + + + 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 g_ptr_array_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 #GPtrArray. + + + + + + a #GPtrArray 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 g_ptr_array_find_with_equal_func(). + + + %TRUE if @needle is one of the elements of @haystack + + + + + pointer array to be searched + + + + + + pointer to look for + + + + 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 + + + + + pointer array to be searched + + + + + + 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 + + + + 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 #GPtrArray + + + + + + the function to call for each array element + + + + user data to pass to the function + + + + + + Frees the memory allocated for the #GPtrArray. If @free_seg 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_seg is %TRUE and no #GDestroyNotify +function has been set for @array. + +This function is not thread-safe. If using a #GPtrArray from multiple +threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() +functions. + + + the pointer array if @free_seg is %FALSE, otherwise %NULL. + The pointer array should be freed using g_free(). + + + + + a #GPtrArray + + + + + + 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 #GPtrArray + + + + + + the index to place the new element at, or -1 to append + + + + the pointer to add. + + + + + + Creates a new #GPtrArray with a reference count of 1. + + + the new #GPtrArray + + + + + + + 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 set @element_free_func +for freeing each element when the array is destroyed either via +g_ptr_array_unref(), when g_ptr_array_free() is called with +@free_segment set to %TRUE or when removing elements. + + + A new #GPtrArray + + + + + + + number of pointers preallocated + + + + A function to free elements with + destroy @array or %NULL + + + + + + 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 g_ptr_array_unref(), when g_ptr_array_free() is called with +@free_segment set to %TRUE or when removing elements. + + + A new #GPtrArray + + + + + + + A function to free elements with + destroy @array or %NULL + + + + + + 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 #GPtrArray + + + + + + + + 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 #GDestroyNotify 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 removed, %FALSE if the pointer + is not found in the array + + + + + a #GPtrArray + + + + + + 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 g_ptr_array_remove(). If @array has a non-%NULL +#GDestroyNotify 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 was found in the array + + + + + a #GPtrArray + + + + + + 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 #GDestroyNotify 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 #GDestroyNotify implementation). + + + the pointer which was removed + + + + + a #GPtrArray + + + + + + 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 g_ptr_array_remove_index(). If @array has a non-%NULL +#GDestroyNotify 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 #GDestroyNotify implementation). + + + the pointer which was removed + + + + + a #GPtrArray + + + + + + 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 #GDestroyNotify function it is +called for the removed elements. + + + the @array + + + + + + + a @GPtrArray + + + + + + 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 g_ptr_array_unref(), when g_ptr_array_free() is called +with @free_segment set to %TRUE or when removing elements. + + + + + + + A #GPtrArray + + + + + + A function to free elements with + destroy @array or %NULL + + + + + + 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 #GDestroyNotify function then it will be +called for the removed elements. + + + + + + + a #GPtrArray + + + + + + 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 + + + + + + + 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 irst arg is +greater than second arg). + +Note that the comparison function for g_ptr_array_sort() doesn't +take the pointers from the array as arguments, it takes pointers to +the pointers in the array. + +This is guaranteed to be a stable sort since version 2.32. + + + + + + + a #GPtrArray + + + + + + comparison function + + + + + + Like g_ptr_array_sort(), but the comparison function has an extra +user data argument. + +Note that the comparison function for g_ptr_array_sort_with_data() +doesn't take the pointers from the array as arguments, it takes +pointers to the pointers in the array. + +This is guaranteed to be a stable sort since version 2.32. + + + + + + + a #GPtrArray + + + + + + comparison function + + + + data to pass to @compare_func + + + + + + Removes the pointer at the given index from the pointer array. +The following elements are moved down one place. The #GDestroyNotify for +@array is *not* called on the removed element; ownership is transferred to +the caller of this function. + + + the pointer which was removed + + + + + a #GPtrArray + + + + + + 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 g_ptr_array_steal_index(). The #GDestroyNotify for @array is +*not* called on the removed element; ownership is transferred to the caller +of this function. + + + the pointer which was removed + + + + + a #GPtrArray + + + + + + 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 +g_ptr_array_free() with @free_segment set to %TRUE. This function +is thread-safe and may be called from any thread. + + + + + + + A #GPtrArray + + + + + + + + + Contains the public fields of a +[Queue][glib-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 + + + + + + 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. + +Sine: 2.32 + + + + + + + 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. 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. + +It is implementation-defined how many threads are allowed to +hold read locks 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 any thread already 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. + + + + + + + a #GRWLock + + + + + + Tries to obtain a write lock on @rw_lock. If any other thread 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 + + + + + + + The GRand struct is an opaque data structure. It should only be +accessed through the g_rand_* functions. + + + 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 + + + + + + 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 + + + + + + + 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. + +Sine: 2.32 + + + + + + + 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 + + + + + + + The g_regex_*() functions implement regular +expression pattern matching using syntax and semantics similar to +Perl regular expression. + +Some functions accept a @start_position argument, setting it 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. +For example, consider the pattern "\Biss\B" which finds occurrences of "iss" +in the middle of words. ("\B" matches only if the current position in the +subject is not a word boundary.) When applied to the string "Mississipi" +from the fourth byte, namely "issipi", it does not match, because "\B" is +always false at the start of the subject, which is deemed to be a word +boundary. However, if the entire string is passed , but with +@start_position set to 4, it finds the second occurrence of "iss" because +it is able to look behind the starting point to discover that it is +preceded by a letter. + +Note that, unless you set the #G_REGEX_RAW flag, all the strings passed +to these functions 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. + +When matching a pattern, "\n" matches only against a "\n" character in +the string, and "\r" matches only a "\r" character. To match any newline +sequence use "\R". This particular group matches either the two-character +sequence CR + LF ("\r\n"), or one of the single characters 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), or PS (paragraph separator, U+2029). + +The behaviour of the dot, circumflex, and dollar metacharacters are +affected by newline characters, the default is to recognize any newline +character (the same characters recognized by "\R"). This can be changed +with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF +compile options, and with #G_REGEX_MATCH_NEWLINE_ANY, +#G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and +#G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also +relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an +unescaped "#" outside a character class is encountered. This indicates +a comment that lasts until after the next newline. + +When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern +matching is changed to be compatible with the way that regular expressions +work in JavaScript. More precisely, a lonely ']' character in the pattern +is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and +you must use the '\u' escape sequence with 4 hex digits to specify a unicode +codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by +the specified number of hex digits, they match 'x' and 'u' literally; also +'\U' always matches 'U' instead of being an error in the pattern. Finally, +pattern matching is modified so that back references to an unset subpattern +group produces a match with the empty string instead of an error. See +pcreapi(3) for more information. + +Creating and manipulating the same #GRegex structure from different +threads is not a problem as #GRegex does not modify its internal +state between creation and destruction, on the other hand #GMatchInfo +is not threadsafe. + +The regular expressions 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 occured. 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]+", 0, 0, 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]+", 0, 0, 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 stings +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", 0, 0, 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 a 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 a 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 +a 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. + + + 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). + + + Optimize the regular expression. If the pattern will + be used many times, then it may be worth the effort to optimize it + to improve the speed of matches. + + + 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'. + + + Usually any newline character or character sequence is + recognized. If this option is set, the only recognized newline character + sequence is '\r\n'. + + + Usually any newline character or character sequence + is recognized. If this option is set, the only recognized newline character + sequences are '\r', '\n', and '\r\n'. Since: 2.34 + + + Usually any newline character or character sequence + is recognised. If this option is set, then "\R" only recognizes the newline + characters '\r', '\n' and '\r\n'. Since: 2.34 + + + Changes behaviour so that it is compatible with + JavaScript rather than PCRE. Since: 2.34 + + + + 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. + + + 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 + + + + 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. + + + + + + + + + + + + + + + + + + + + + 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][glib-Type-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. + +The return value is the new start of the list, which may +have changed, so 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)); +]| + + + the new start of the #GSList + + + + + + + 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. + + + + + + + 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). + + + + + + + a pointer to 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 new 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. + +The return value is the new start of the list, which +may 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"); +]| + + + 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 #GSourceFunc to leave +the #GSource in the main loop. + + + + + Cast a function pointer to a #GSourceFunc, 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 +g_child_watch_source_new() is #GChildWatchFunc, which accepts more arguments +than #GSourceFunc. Casting the function with `(GSourceFunc)` to call +g_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 #GSourceFunc to remove +the #GSource from the main loop. + + + + + The square root of two. + + + + + 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. + + + + a structure type, e.g. #GtkWidget + + + a field in the structure, e.g. @window + + + + + The standard delimiters, used in g_strdelimit(). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The data structure representing a 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][glib-Sequences] 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 length 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 #GSource structure. The size is specified to +allow creating structures derived from #GSource that contain +additional data. The size passed in must be at least +`sizeof (GSource)`. + +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. + + + the newly-created #GSource. + + + + + structure containing functions that implement + the sources behavior. + + + + size of the #GSource structure to create. + + + + + + Adds @child_source to @source as a "polled" source; when @source is +added to a #GMainContext, @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. (@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). + +@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 #GSource. +Do not call this API on a #GSource that you did not create. + + + + + + + a #GSource + + + + a second #GSource that @source should "poll" + + + + + + Adds a file descriptor to the set of file descriptors polled for +this source. This is usually combined with g_source_new() to add an +event source. The event source's check function will typically test +the @revents field in the #GPollFD struct and return %TRUE if events need +to be processed. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource 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 #GSource + + + + a #GPollFD 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 g_source_remove_unix_fd() or +g_source_modify_unix_fd(). + +It is not necessary to remove the fd before destroying the source; it +will be cleaned up automatically. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + +As the name suggests, this function is not available on Windows. + + + an opaque tag + + + + + a #GSource + + + + the fd to monitor + + + + an event mask + + + + + + Adds a #GSource to a @context so that it will be executed within +that context. Remove it by calling g_source_destroy(). + + + the ID (greater than 0) for the source within the + #GMainContext. + + + + + a #GSource + + + + a #GMainContext (if %NULL, the default context will be used) + + + + + + Removes a source from its #GMainContext, if any, and mark 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 #GSource: if you still hold a reference, use +g_source_unref() to drop it. + + + + + + + a #GSource + + + + + + Checks whether a source is allowed to be called recursively. +see g_source_set_can_recurse(). + + + whether recursion is allowed. + + + + + a #GSource + + + + + + Gets the #GMainContext with which the source is associated. + +You can call this on a source that has been destroyed, provided +that the #GMainContext it was attached to still exists (in which +case it will return that #GMainContext). In particular, you can +always call this function on the source returned from +g_main_current_source(). But calling this function on a source +whose #GMainContext has been destroyed is an error. + + + the #GMainContext with which the + source is associated, or %NULL if the context has not + yet been added to a source. + + + + + a #GSource + + + + + + This function ignores @source and is otherwise the same as +g_get_current_time(). + use g_source_get_time() instead + + + + + + + a #GSource + + + + #GTimeVal 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 g_main_context_find_source_by_id(). + +You can only call this function while the source is associated to a +#GMainContext instance; calling this function before g_source_attach() +or after g_source_destroy() yields undefined behavior. The ID returned +is unique within the #GMainContext instance passed to g_source_attach(). + + + the ID (greater than 0) for the source + + + + + a #GSource + + + + + + Gets a name for the source, used in debugging and profiling. The +name may be #NULL if it has never been set with g_source_set_name(). + + + the name of the source + + + + + a #GSource + + + + + + Gets the priority of a source. + + + the priority of the source + + + + + a #GSource + + + + + + Gets the "ready time" of @source, as set by +g_source_set_ready_time(). + +Any time before the current monotonic time (including 0) is an +indication that the source will fire immediately. + + + the monotonic ready time, -1 for "never" + + + + + a #GSource + + + + + + Gets the time to be used when checking this source. The advantage of +calling this function over calling g_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 g_get_monotonic_time(). + + + the monotonic time in microseconds + + + + + a #GSource + + + + + + 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. + +|[<!-- language="C" --> +static gboolean +idle_callback (gpointer data) +{ + SomeWidget *self = data; + + GDK_THREADS_ENTER (); + // do stuff with self + self->idle_id = 0; + GDK_THREADS_LEAVE (); + + return G_SOURCE_REMOVE; +} + +static void +some_widget_do_stuff_later (SomeWidget *self) +{ + self->idle_id = g_idle_add (idle_callback, self); +} + +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); +} +]| + +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. + +|[<!-- language="C" --> +static gboolean +idle_callback (gpointer data) +{ + SomeWidget *self = data; + + GDK_THREADS_ENTER (); + if (!g_source_is_destroyed (g_main_current_source ())) + { + // do stuff with self + } + GDK_THREADS_LEAVE (); + + return FALSE; +} +]| + +Calls to this function from a thread other than the one acquired by the +#GMainContext the #GSource 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 + + + + + a #GSource + + + + + + Updates the event mask to watch for the fd identified by @tag. + +@tag is the tag returned from g_source_add_unix_fd(). + +If you want to remove a fd, don't set its event mask to zero. +Instead, call g_source_remove_unix_fd(). + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + +As the name suggests, this function is not available on Windows. + + + + + + + a #GSource + + + + the tag from g_source_add_unix_fd() + + + + the new event mask to watch + + + + + + Queries the events reported for the fd 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 #GSource. +Do not call this API on a #GSource that you did not create. + +As the name suggests, this function is not available on Windows. + + + the conditions reported on the fd + + + + + a #GSource + + + + the tag from g_source_add_unix_fd() + + + + + + Increases the reference count on a source by one. + + + @source + + + + + a #GSource + + + + + + Detaches @child_source from @source and destroys it. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + + + + + + + a #GSource + + + + a #GSource previously passed to + g_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 #GSource. +Do not call this API on a #GSource that you did not create. + + + + + + + a #GSource + + + + a #GPollFD structure previously passed to g_source_add_poll(). + + + + + + Reverses the effect of a previous call to g_source_add_unix_fd(). + +You only need to call this if you want to remove an fd 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 #GSource. +Do not call this API on a #GSource that you did not create. + +As the name suggests, this function is not available on Windows. + + + + + + + a #GSource + + + + the tag from g_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 G_SOURCE_FUNC() to avoid warnings about +incompatible function types. + +See [memory management of sources][mainloop-memory-management] 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 g_idle_add() or g_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. + + + + + + + the source + + + + a callback function + + + + the data to pass to callback function + + + + a function to call when @data is no longer in use, or %NULL. + + + + + + Sets the callback function storing the data as a refcounted callback +"object". This is used internally. Note that calling +g_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 #GSource + + + + whether recursion is allowed for this source + + + + + + Sets the source functions (can be used to override +default implementations) of an unattached source. + + + + + + + a #GSource + + + + the new #GSourceFuncs + + + + + + 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" or whatever it is. + +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 #GSourceFuncs +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 g_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. + + + + + + + a #GSource + + + + 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 #GSource + + + + the new priority. + + + + + + Sets a #GSource 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 #GSource which has already been +destroyed with g_source_destroy(). + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + + + + + + + a #GSource + + + + the monotonic time at which the source will be ready, + 0 for "immediately", -1 for "never" + + + + + + 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 #GSource + + + + + + Removes the source with the given ID from the default main context. You must +use g_source_destroy() for sources added to a non-default main context. + +The ID of a #GSource is given by g_source_get_id(), or will be +returned by the functions g_source_attach(), g_idle_add(), +g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), +g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and +g_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 g_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. + + + For historical reasons, this function always returns %TRUE + + + + + 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. + + + + + The @source_funcs passed to g_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. + + + + + 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 g_idle_add(), g_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 g_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 #GSource ID + + + + debug name for the source + + + + + + + The `GSourceCallbackFuncs` struct contains +functions for managing callback objects. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This is just a placeholder for #GClosureMarshal, +which cannot be used here for dependency reasons. + + + + + + + Specifies the type of function passed to g_timeout_add(), +g_timeout_add_full(), g_idle_add(), and g_idle_add_full(). + +When calling g_source_set_callback(), you may need to cast a function of a +different type to this type. Use G_SOURCE_FUNC() to avoid warnings about +incompatible function types. + + + %FALSE if the source should be removed. #G_SOURCE_CONTINUE and +#G_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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 to pass 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 abolute 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 + + + + 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. + + + + The GString struct contains the public fields of a GString. + + + 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. + + + + 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, escaped 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 + + + + + + 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(). + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + + An opaque data structure representing String Chunks. +It should only be accessed by using the following functions. + + + 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. + + + + + + + Creates a unique temporary directory for each unit test and uses +g_set_user_dirs() to set 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 +g_test_run() is called, so calls to (for example) g_get_user_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. + + - g_get_home_dir() + - g_get_user_cache_dir() + - g_get_system_config_dirs() + - g_get_user_config_dir() + - g_get_system_data_dirs() + - g_get_user_data_dir() + - g_get_user_runtime_dir() + +The subdirectories may not be created by the test harness; as with normal +calls to functions like g_get_user_cache_dir(), the caller must be prepared +to create the directory if it doesn’t exist. + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + 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 +g_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. + + + 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 g_test_trap_subprocess() to control input and output. + +Note that in contrast with g_test_trap_fork(), the default is to +not show stdout and stderr. + + + 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 g_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 g_test_trap_assert_stderr(). + + + + An opaque structure representing a test suite. + + + Adds @test_case to @suite. + + + + + + + a #GTestSuite + + + + a #GTestCase + + + + + + Adds @nestedsuite to @suite. + + + + + + + a #GTestSuite + + + + another #GTestSuite + + + + + + + Test traps are guards around forked tests. +These flags determine what traps to set. + #GTestTrapFlags is used only with g_test_trap_fork(), +which is deprecated. g_test_trap_subprocess() uses +#GTestSubprocessFlags. + + + 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. + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + + + + + + 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 + + + + + + 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 + + + + + + The #GThreadPool struct represents a thread pool. It has three +public read-only members, but the underlying struct is bigger, +so you must not copy this struct. + + + 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, the functions does not return before all +tasks to be processed (dependent on @immediate, whether all +or only the currently running) are ready. +Otherwise the 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. + +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. + +@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 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 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(). + + + + + + + + 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 + + + + + + + #GTimeZone is an opaque structure whose members cannot be accessed +directly. + + + Creates a #GTimeZone corresponding to @identifier. + +@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, or 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 + + + + + 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]]`. + + + a timezone at the given offset from UTC + + + + + 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 the 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 + + + + + + + Opaque datatype that records a start time. + + + 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() + + + + + + Each piece of memory that is pushed onto the stack +is cast to a GTrashStack*. + #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 traveral 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 + ![](Sorted_binary_tree_inorder.svg) +- Pre order: F, B, A, D, C, E, G, I, H + ![](Sorted_binary_tree_preorder.svg) +- Post order: A, C, E, D, B, H, I, G, F + ![](Sorted_binary_tree_postorder.svg) +- Level order: F, B, G, A, D, I, C, E, H + ![](Sorted_binary_tree_breadth-first_traversal.svg) + + + vists 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][glib-Balanced-Binary-Trees]. + For [n-ary trees][glib-N-ary-Trees], it + vists 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][glib-Balanced-Binary-Trees]. It should be +accessed only by using the following functions. + + + 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 + + + + + + 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. + +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. + + + + + + + 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 number of nodes in a #GTree. + + + the number of nodes in @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. + + + %TRUE if the key was found (prior to 2.8, this function + returned nothing) + + + + + a #GTree + + + + the key to remove + + + + + + Inserts a new key and value into a #GTree similar to g_tree_insert(). +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. + + + + + + + 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 + + + + + + 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][glib-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 + + + + + + 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 + + + + + + + This macro can be used to mark a function declaration as unavailable. +It must be placed before the function declaration. Use of a function +that has been annotated with this macros will produce a compiler warning. + + + + the major version that introduced the symbol + + + the minor version that introduced the symbol + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. Includes ":/?#[]@". + + + + + Subcomponent delimiter characters as defined in RFC 3986. 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](http://www.unicode.org/unicode/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 + + + 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 + + + + 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 + + + + 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 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() + + + + + + 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 #GVariantBuilder must be initialized if it is +used together with g_auto() to avoid warnings or crashes if +function returns before g_variant_builder_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_builder_init(), but it cannot be assigned to a variable. + +The passed @variant_type should be a static GVariantType 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 #GVariantBuilder is valid. + +|[ + g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING); +]| + + + + a const GVariantType* + + + + + 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(). + +|[ + g_autoptr(GVariant) variant = get_asv_variant (); + g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant); +]| + + + + a GVariant* + + + + + Converts a string to a const #GVariantType. Depending on the +current debugging level, this function may perform a runtime check +to ensure that @string is a valid GVariant type string. + +It is always a programmer error to use this macro with an invalid +type string. If in doubt, use g_variant_type_string_is_valid() to +check if the string is valid. + +Since 2.24 + + + + a well-formed #GVariantType type string + + + + + Portable way to copy va_list variables. + +In order to use this function, you must include string.h yourself, +because this macro may use memmove() and GLib does not include +string.h for you. + + + + the va_list variable to place a copy of @ap2 in + + + a va_list + + + + + + + + + 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 DBus, or when saving settings using GSettings. + +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: + +|[<!-- language="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-pointers]. + +The range of possible values is determined by the type. + +The type system used by #GVariant is #GVariantType. + +#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 g_variant_ref() and +g_variant_unref(). #GVariant also has floating reference counts -- +see g_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 serialised +form. It works particularly well with data located in memory-mapped +files. It can perform nearly all deserialisation operations in a +small constant time, usually touching only a single memory page. +Serialised #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 #GVariantType for +exceptions. (However, #GVariant's serialisation format is not the same +as the serialisation format of a D-Bus message body: use #GDBusMessage, +in the gio library, for those.) + +For space-efficiency, the #GVariant serialisation 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 #GMappedFile, and call g_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 serialised data, memory for the type +information cache, buffer management memory and memory for the +#GVariant structure itself. + +## Serialised Data Memory + +This is the memory that is used for storing GVariant data in +serialised 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 serialisation. + +If we add an item "width" that maps to the int32 value of 500 then +we will use 4 byte 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 deserialisation. + +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 malloc 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 malloc 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 #GHashTable 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 serialised 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 g_free() or a g_slice_free() or +even g_mapped_file_unref(). + +One buffer management structure is used for each chunk of +serialised 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 +serialised 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 g_variant_unref()). The +type information is shared. The serialised data and the buffer +management structure for that serialised 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 serialised data, 16 bytes for buffer management and 24 +bytes for the #GVariant instance, or a total of 160 bytes, plus +malloc overhead. If we were to use g_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 serialised 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]. 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-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 serialised 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 serialised-mode #GVariant instance. This is the +inner interface for creation of new serialised 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 serialised 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 serialised data in normal form then +@trusted should be %TRUE. This applies to serialised 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 serialised 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 @string. +@string 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-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-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-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(). + +This function consumes @string. g_free() will be called on @string +when it is no longer required. + +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-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). + +The returned value is always in normal form and is marked as trusted. + + + 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]. +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-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-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. + +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 serialised 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 deserialised from a +corrupted serialised 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 serialised form, this function +is O(1). If the value is not already in serialised form, +serialisation occurs implicitly and is approximately O(n) in the size +of the result. + +To deserialise the data returned by this function, in addition to the +serialised 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 +serialised #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 +serialised data). + + + the serialised form of @value, or %NULL + + + + + a #GVariant instance + + + + + + Returns a pointer to the serialised 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 serialised 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][gvariant-serialised-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 serialised 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 + + + + + a 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 + + + + + a 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 + + + + + a 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. + +It makes sense to call this function if you've received #GVariant +data from untrusted sources and you want to ensure your serialised +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 serialised 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 serialised 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, and will never be %NULL. + +If @length is non-%NULL then the length of the string (in bytes) is +returned there. For trusted values, this information is already +known. For untrusted values, a strlen() will be performed. + +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-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 +serialised 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-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]. + +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 serialised 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 deserialise the +serialised 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 serialised 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 alway 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]. + +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 +g_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 g_variant_print()". + + + 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(). + + + 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-varargs]. + +This function might be used as follows: + +|[<!-- language="C" --> +GVariant * +make_pointless_dictionary (void) +{ + GVariantBuilder builder; + int i; + + g_variant_builder_init (&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-varargs]. + +This function might be used as follows: + +|[<!-- language="C" --> +GVariant * +make_pointless_dictionary (void) +{ + GVariantBuilder builder; + int i; + + g_variant_builder_init (&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. + +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 + + + + + + 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. 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-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 releated 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-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-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 + + + + This section introduces the GVariant 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 GVariant. + +The first major change with respect to the D-Bus type system is the +introduction of maybe (or "nullable") types. Any type in GVariant 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 GVariant 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 GVariant, 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, GVariant types are described with strings ("type +strings"). Subject to the differences mentioned above, these strings +are of the same form as those found in DBus. 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. GVariant deals with single values directly so GVariant type +strings always describe the type of exactly one value. This means +that a D-Bus signature string is generally not a valid GVariant 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, +g_variant_get_type() will never return an indefinite type, but +calling g_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 #GtkBin can exist (since #GtkBin is an abstract class), +but a #GtkWindow can certainly be instantiated, and you would say +that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of +#GtkBin). + +## GVariant Type Strings + +A GVariant 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 +g_variant_type_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, #GVariant +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 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 #GVariantType corresponding to the type string given +by @type_string. It is appropriate to call g_variant_type_free() on +the return value. + +It is a programmer error to call this function with an invalid type +string. Use g_variant_type_string_is_valid() if you are unsure. + + + a new #GVariantType + + + + + a valid GVariant type string + + + + + + Constructs the type corresponding to an array of elements of the +type @type. + +It is appropriate to call g_variant_type_free() on the return value. + + + a new array #GVariantType + +Since 2.24 + + + + + a #GVariantType + + + + + + 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 g_variant_type_free() on the return value. + + + a new dictionary entry #GVariantType + +Since 2.24 + + + + + a basic #GVariantType + + + + a #GVariantType + + + + + + Constructs the type corresponding to a maybe instance containing +type @type or Nothing. + +It is appropriate to call g_variant_type_free() on the return value. + + + a new maybe #GVariantType + +Since 2.24 + + + + + a #GVariantType + + + + + + 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 g_variant_type_free() on the return value. + + + a new tuple #GVariantType + +Since 2.24 + + + + + an array of #GVariantTypes, one for each item + + + + + + the length of @items, or -1 + + + + + + Makes a copy of a #GVariantType. It is appropriate to call +g_variant_type_free() on the return value. @type may not be %NULL. + + + a new #GVariantType + +Since 2.24 + + + + + a #GVariantType + + + + + + Returns a newly-allocated copy of the type string corresponding to +@type. The returned string is nul-terminated. It is appropriate to +call g_free() on the return value. + + + the corresponding type string + +Since 2.24 + + + + + a #GVariantType + + + + + + 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 #GVariantType + + + + + + 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 g_variant_type_is_subtype_of(). + +The argument types of @type1 and @type2 are only #gconstpointer to +allow use with #GHashTable without function pointer casting. For +both arguments, a valid #GVariantType must be provided. + + + %TRUE if @type1 and @type2 are exactly equal + +Since 2.24 + + + + + a #GVariantType + + + + a #GVariantType + + + + + + 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 g_variant_type_next() provides an iterator +interface over tuple and dictionary entry types. + + + the first item type of @type, or %NULL + +Since 2.24 + + + + + a tuple or dictionary entry #GVariantType + + + + + + Frees a #GVariantType that was allocated with +g_variant_type_copy(), g_variant_type_new() or one of the container +type constructor functions. + +In the case that @type is %NULL, this function does nothing. + +Since 2.24 + + + + + + + a #GVariantType, or %NULL + + + + + + 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 g_variant_type_peek_string(). + + + the length of the corresponding type string + +Since 2.24 + + + + + a #GVariantType + + + + + + Hashes @type. + +The argument type of @type is only #gconstpointer to allow use with +#GHashTable without function pointer casting. A valid +#GVariantType must be provided. + + + the hash value + +Since 2.24 + + + + + a #GVariantType + + + + + + 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 + + + + + a #GVariantType + + + + + + 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 + + + + + a #GVariantType + + + + + + 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 + + + + + a #GVariantType + + + + + + 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 #GVariant instance may not have an indefinite type, so calling +this function on the result of g_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 + + + + + a #GVariantType + + + + + + 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 + + + + + a #GVariantType + + + + + + 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 + + + + + a #GVariantType + + + + + + 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 + + + + + a #GVariantType + + + + a #GVariantType + + + + + + 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 + + + + + a #GVariantType + + + + + + Determines if the given @type is the variant type. + + + %TRUE if @type is the variant type + +Since 2.24 + + + + + a #GVariantType + + + + + + 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 +g_variant_type_first(). + + + the key type of the dictionary entry + +Since 2.24 + + + + + a dictionary entry #GVariantType + + + + + + 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 #GVariantType + + + + + + Determines the next item type of a tuple or dictionary entry +type. + +@type must be the result of a previous call to +g_variant_type_first() or g_variant_type_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 a tuple. + + + the next #GVariantType after @type, or %NULL + +Since 2.24 + + + + + a #GVariantType 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 g_variant_type_get_string_length(). + +To get a nul-terminated string, see g_variant_type_dup_string(). + + + the corresponding type string (not nul-terminated) + +Since 2.24 + + + + + a #GVariantType + + + + + + 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 #GVariantType + + + + + + + + + + + + + + + + + + + + + + + + + + + + Checks if @type_string is a valid GVariant type string. This call is +equivalent to calling g_variant_type_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 g_variant_type_string_is_valid(). + + + %TRUE if a valid type string was found + + + + + a pointer to any string + + + + the end of @string, or %NULL + + + + location to store the end pointer, or %NULL + + + + + + + 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 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() + + + + + + 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. + +- 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. + + + + + 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. + + + + a #GArray + + + 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 example gets a pointer to an element in a #GArray: +|[<!-- language="C" --> + EDayViewEvent *event; + // This gets a pointer to the 4th element in the array of + // EDayViewEvent structs. + event = &g_array_index (events, EDayViewEvent, 3); +]| + + + + a #GArray + + + 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. + + + + a #GArray + + + the index to place the element at + + + the value to insert into the array + + + + + Adds the value on to the start of the array. The array will grow in +size automatically if necessary. + +This operation is slower than g_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. + + + + a #GArray + + + the value to prepend to the #GArray + + + + + Determines the numeric value of a character as a decimal digit. +Differs from g_unichar_digit_value() because it takes a char, so +there's no worry about sign extension if characters are signed. + + + If @c is a decimal digit (according to g_ascii_isdigit()), + its numeric value. Otherwise, -1. + + + + + 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 g_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 @G_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 #gdouble 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 returned buffer is guaranteed to be nul-terminated. + +If you just want to want to serialize the value into a +string, use g_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 #gdouble 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. + + + a newly-allocated string, with all the upper case + characters in @str converted to lower case, with semantics that + exactly match g_ascii_tolower(). (Note that this is unlike the + old g_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 +%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of +bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. + +See g_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, otherwise %FALSE. + + + + + a string + + + + 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 +%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of +bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. + +See g_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, otherwise %FALSE. + + + + + 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. + +Unlike the BSD strcasecmp() 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 g_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 #gdouble 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 g_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 #gdouble 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, %G_MAXINT64 or %G_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 #gint64 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 +never 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, %G_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 #guint64 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. + + + a newly allocated string, with all the lower case + characters in @str converted to upper case, with semantics that + exactly match g_ascii_toupper(). (Note that this is unlike the + old g_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. + +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 converting @c to lower case. If @c is + not an ASCII upper case letter, @c is returned unchanged. + + + + + any character + + + + + + Convert a character to ASCII upper case. + +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 converting @c to upper case. If @c is not + an ASCII lower case letter, @c is returned unchanged. + + + + + any character + + + + + + Determines the numeric value of a character as a hexidecimal +digit. Differs from g_unichar_xdigit_value() because it takes +a char, so there's no worry about sign extension if characters +are signed. + + + If @c is a hex digit (according to g_ascii_isxdigit()), + its numeric value. Otherwise, -1. + + + + + 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 g_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. + + + + an 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. + + + + an 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 g_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. + +|[<!-- language="C" --> + g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected)); +]| + + + + pointer to a buffer + + + length of @m1 + + + pointer to another buffer + + + length of @m2 + + + + + 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 g_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. + +|[<!-- language="C" --> + g_assert_cmpstr (mystring, ==, "fubar"); +]| + + + + a string (may be %NULL) + + + The comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + + + another string (may be %NULL) + + + + + 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 #GVariants. 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 +g_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 #GError. + +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, possibly %NULL + + + 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 g_assert(), this macro is unaffected by whether +`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, +conversely, g_assert() should not be used in tests. + +See g_test_set_nonfatal_assertions(). + + + + the expression to check + + + + + Debugging macro to check that a #GError 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, possibly %NULL + + + + + 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 g_assert(), this macro is unaffected by whether +`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, +conversely, g_assert() should not be used in tests. + +See g_test_set_nonfatal_assertions(). + + + + the expression to check + + + + + 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 g_assert(), this macro is unaffected by whether +`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, +conversely, g_assert() should not be used in tests. + +See g_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 g_assert(), this macro is unaffected by whether +`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, +conversely, g_assert() should not be used in tests. + +See g_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 + + + + + + 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). + + + 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; }`. + + + 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. + + + %TRUE if the exchange took place + + + + + a pointer to a #gint or #guint + + + + the value to compare with + + + + the value to conditionally replace with + + + + + + 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. + + + %TRUE if the resultant value is zero + + + + + a pointer to a #gint or #guint + + + + + + 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 (before the get). + + + 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. + + + + + + + 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. + + + 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 (after the set). + + + + + + + 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. + + + 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. + + + 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. + + + 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. + + + %TRUE if the exchange took place + + + + + a pointer to a #gpointer-sized value + + + + the value to compare with + + + + the value to conditionally replace with + + + + + + Gets the current value of @atomic. + +This call acts as a full compiler and hardware +memory barrier (before the get). + + + 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. + + + 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 (after the set). + + + + + + + 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. + + + 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 +referenc 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. + + + + + + + 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. + + + %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. + + + + + + + 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) / 72 + 1 bytes of extra space. + +@break_lines is typically used when putting base64-encoded data in emails. +It breaks the lines at 72 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. + + + + + + + a pointer to an integer + + + + a bit value between 0 and 31 + + + + + + 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. + + + %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. + + + + + + + a pointer to an integer + + + + a bit value between 0 and 31 + + + + + + + + + + + Creates a filename from a series of elements using the correct +separator for filenames. + +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. + + + a newly-allocated string that must be freed with + g_free(). + + + + + the first element in the path + + + + remaining elements in path, terminated by %NULL + + + + + + Behaves exactly like g_build_filename(), but takes the path elements +as a va_list. This function is mainly meant for language bindings. + + + a newly-allocated string that must be freed + with g_free(). + + + + + the first element in the path + + + + va_list of remaining elements in path + + + + + + 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. + + + a newly-allocated string that must be freed + with g_free(). + + + + + %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. + + + a newly-allocated string that must be freed with + g_free(). + + + + + a string used to separator 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 varargs. This function is mainly +meant for language bindings. + + + a newly-allocated string that must be freed + with g_free(). + + + + + a string used to separator the elements of the path. + + + + %NULL-terminated + array of strings containing the path elements. + + + + + + + + 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 element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free(). + + + + + a #GByteArray + + + + + + if %TRUE the actual byte data is freed as well + + + + + + Transfers the data from the #GByteArray into a new immutable #GBytes. + +The #GByteArray is freed unless the reference count of @array is greater +than one, the #GByteArray wrapper is preserved but the size of @array +will be set to zero. + +This is identical to using g_bytes_new_take() and g_byte_array_free() +together. + + + a new immutable #GBytes representing same + byte data that was in the array + + + + + a #GByteArray + + + + + + + + Creates a new #GByteArray with a reference count of 1. + + + the new #GByteArray + + + + + + + Create byte array containing the data. The data will be owned by the array +and will be freed with g_free(), i.e. it could be allocated using g_strdup(). + + + a new #GByteArray + + + + + + + byte data for the array + + + + + + length of @data + + + + + + 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 #GByteArray + + + + + + + + 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, #G_PRIORITY_DEFAULT. + +If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() +you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to +the spawn function for the child watching to work. + +Note that on platforms where #GPid must be explicitly closed +(see g_spawn_close_pid()) @pid must not be closed while the +source is still active. Typically, you will want to call +g_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 +g_child_watch_source_new() apply to this function. + +This internally creates a main loop source using +g_child_watch_source_new() and attaches it to the main loop context +using g_source_attach(). You can do these steps manually if you +need greater control. + + + the ID (greater than 0) of the event source. + + + + + process id to watch. On POSIX the positive pid of a child +process. On Windows 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 g_spawn_async() or g_spawn_async_with_pipes() +you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to +the spawn function for the child watching to work. + +In many programs, you will want to call g_spawn_check_exit_status() +in the callback to determine whether or not the child exited +successfully. + +Also, note that on platforms where #GPid must be explicitly closed +(see g_spawn_close_pid()) @pid must not be closed while the source +is still active. Typically, you should invoke g_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 +g_child_watch_source_new() apply to this function. + +This internally creates a main loop source using +g_child_watch_source_new() and attaches it to the main loop context +using g_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 #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + + + + process to watch. On POSIX the positive pid of a child process. On +Windows 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, or %NULL + + + + + + Creates a new child_watch source. + +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. + +Note that child watch sources can only be used in conjunction with +`g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used. + +Note that on platforms where #GPid must be explicitly closed +(see g_spawn_close_pid()) @pid must not be closed while the +source is still active. Typically, you will want to call +g_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` 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 SIGCHILD + +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` for specific processes other than @pid remains a +valid thing to do. + + + the newly-created child watch source + + + + + process to watch. On POSIX the positive pid of a child process. On +Windows a handle for a process (which doesn't have to be a child). + + + + + + If @err or *@err is %NULL, does nothing. Otherwise, +calls g_error_free() on *@err and sets *@err to %NULL. + + + + + + + Clears a numeric handler, such as a #GSource ID. + +@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 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 `GDestroyNotify` using the standard calling +convention for the platform that GLib was compiled for; otherwise the program +will experience undefined behaviour. + + + + + + + a pointer to a variable, struct member etc. holding a + pointer + + + + a function to which a gpointer can be passed, to destroy *@pp + + + + + + 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. + +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. + + + %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. + 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. + 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. 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 + + + + + + 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). + + + + + + 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 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 he wishes, 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 + + + + + + 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][setlocale]-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 the buffer was too small + + + + + destination buffer + + + + buffer size + + + + format string + + + + valid #GDate + + + + + + 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 + + + + + + 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 + + + + + + Hashes @datetime into a #guint, suitable for use within #GHashTable. + + + a #guint containing the hash + + + + + a #GDateTime + + + + + + 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 + + + + + + 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 '=' + + + + + + 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 @errno + + + + + 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. + + + 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, with good error checking. +If a file called @filename already exists it will be overwritten. + +This write 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), 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. + +- 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. + + + %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 + + + + + + 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. +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 + } +]| + +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. + + + 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][setlocale]. + +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][setlocale]. + +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 + + + + + + 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-precision] + + + + the arguments to insert in the output. + + + + + + Frees the memory pointed to by @mem. + +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 + + + + + + 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][setlocale]; 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. + +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 + + + + + Equivalent to the UNIX gettimeofday() function, but portable. + +You may find g_get_real_time() to be more convenient. + #GTimeVal is not year-2038-safe. Use g_get_real_time() + instead. + + + + + + + #GTimeVal 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][setlocale]. +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. + +For example, if @locale is "fr_BE", then the returned list +is "fr_BE", "fr". + +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. + +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() but it +may not always be possible to do this. + + + the monotonic time, in microseconds + + + + + 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 + + + + + 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 call is functionally equivalent to g_get_current_time() except +that the return value is often more convenient than dealing with a +#GTimeVal. + +You should only use this call if you are actually interested in the real +wall-clock time. g_get_monotonic_time() is probably more useful for +measuring intervals. + + + the number of microseconds since January 1, 1970 UTC. + + + + + 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 +CSIDL_COMMON_APPDATA folder. This information will not roam and is available +to anyone using the computer. + + + + 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 CSIDL_COMMON_APPDATA and +CSIDL_COMMON_DOCUMENTS. + +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. + + + + 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 `CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache). + + + 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 `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). +Note that in this case on Windows it will be the same +as what g_get_user_data_dir() returns. + + + 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 `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). +Note that in this case on Windows it will be the same +as what g_get_user_config_dir() returns. + + + 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. + + + 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 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. + +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 + + + + + + + + + This function is deprecated and will be removed in the next major +release of GLib. It does nothing. + + + + 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 + + + + + + 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 + + + + + + + + + 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(). + +You can pass %NULL for @lookup_key, 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 + + + + + + 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 + + + + + + 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".) + + + %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. + + + 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, #G_PRIORITY_DEFAULT_IDLE. If the function +returns %FALSE it is automatically removed from the list of event +sources and will not be called again. + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +This internally creates a main loop source using g_idle_source_new() +and attaches it to the global #GMainContext using g_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 %FALSE it is automatically +removed from the list of event sources and will not be called again. + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +This internally creates a main loop source using g_idle_source_new() +and attaches it to the global #GMainContext using g_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 #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 + + + + + + Removes the idle function with the given data. + + + %TRUE if an idle source was found and removed. + + + + + the data for the idle source's callback. + + + + + + Creates a new idle source. + +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. Note that the default priority for idle sources is +%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which +have a default priority of %G_PRIORITY_DEFAULT. + + + the newly-created idle source + + + + + 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. + +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][setlocale]. 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][setlocale] 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, G_BREAKPOINT() is called +to terminate the program. See the documentation for G_BREAKPOINT() for +details of the debugging options this provides. + +If g_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][using-structured-logging] this will +output via the structured log writer function (see g_log_set_writer_func()). + + + + + + + the log domain, usually #G_LOG_DOMAIN, or %NULL +for the default + + + + the log level, either from #GLogLevelFlags + 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; g_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 G_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 + aplication. + +- `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. + +stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, +%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for +the rest. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][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 g_log() which is unused + + + + + + Removes the log handler. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + + + + + + + the log domain + + + + the id of the handler, which was returned + in g_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. +%G_LOG_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](glib-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 g_log_structured() and +g_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][using-structured-logging]. + + + the old fatal mask + + + + + the mask containing bits set for each level + of error which is to be fatal + + + + + + 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 +g_log_default_handler() as default log handler. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][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. +%G_LOG_LEVEL_ERROR is always fatal. + +This has no effect on structured log messages (using g_log_structured() or +g_log_structured_array()). To change the fatal behaviour for specific log +messages, programs must install a custom log writer function using +g_log_set_writer_func(). See +[Using Structured Logging][using-structured-logging]. + +This function is mostly intended to be used with +%G_LOG_LEVEL_CRITICAL. You should typically not set +%G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or +%G_LOG_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 #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION +bit flags. + +Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if +you want to set a handler for this log level you must combine it with +#G_LOG_FLAG_FATAL. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + +Here is an example for adding a log handler for all warning messages +in the default domain: +|[<!-- language="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+: +|[<!-- language="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: +|[<!-- language="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, or %NULL for the default "" + 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 #G_LOG_FLAG_FATAL and + #G_LOG_FLAG_RECURSION bit flags. + + + + the log handler function + + + + data passed to the log handler + + + + + + Like g_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][using-structured-logging]. + + + the id of the new handler + + + + + the log domain, or %NULL for the default "" + 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 #G_LOG_FLAG_FATAL and + #G_LOG_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 +(g_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 g_log_set_writer_func(). If the +message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will +be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns +%G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. +See the documentation for #GLogWriterFunc 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 g_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. + +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, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), +g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including +glib.h. + +For example: +|[<!-- language="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 g_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: +|[<!-- language="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 #GLogLevelFlags, 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 g_log_set_writer_func(). If the +message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will +be aborted at the end of this function. + +See g_log_structured() for more documentation. + +This assumes that @log_level is already present in @fields (typically as the +`PRIORITY` field). + + + + + + + log level, either from #GLogLevelFlags, 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 #GVariant. 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 String +(#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 +g_variant_print() will be used to convert the value into a string. + +For more details on its usage and about the parameters, see g_log_structured(). + + + + + + + log domain, usually %G_LOG_DOMAIN + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + a dictionary (#GVariant 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 #GLogWriterFunc, and is the default writer used +if no other is set using g_log_set_writer_func(). + +As with g_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. + + + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + + + + + log level, either from #GLogLevelFlags, 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 g_log_set_writer_func() + + + + + + 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 g_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 #GLogLevelFlags, 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 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: +|[<!-- language="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 #GLogWriterFunc. + +If GLib has been compiled without systemd support, this function is still +defined, but will always return %G_LOG_WRITER_UNHANDLED. + + + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + + + + + log level, either from #GLogLevelFlags, 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 g_log_set_writer_func() + + + + + + Format a structured log message and print it to either `stdout` or `stderr`, +depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages +are sent to `stdout`; 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, 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 #GLogWriterFunc. + + + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + + + + + log level, either from #GLogLevelFlags, 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 g_log_set_writer_func() + + + + + + Check whether the given @output_fd file descriptor supports ANSI color +escape sequences. 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 + + + + + + Logs an error or debugging message. + +If the log level has been set as fatal, G_BREAKPOINT() is called +to terminate the program. See the documentation for G_BREAKPOINT() for +details of the debugging options this provides. + +If g_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][using-structured-logging] this will +output via the structured log writer function (see g_log_set_writer_func()). + + + + + + + the log domain, or %NULL for the default "" +application domain + + + + the log level + + + + the message format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 +g_main_context_get_thread_default(). + + + the global default main context. + + + + + Gets the thread-default #GMainContext 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 +g_main_context_ref_thread_default() to get a #GMainContext to add +their #GSources 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 +g_main_context_ref_thread_default() instead. + + + the thread-default #GMainContext, or +%NULL if the thread-default context is the global default context. + + + + + Gets the thread-default #GMainContext for this thread, as with +g_main_context_get_thread_default(), but also adds a reference to +it with g_main_context_ref(). In addition, unlike +g_main_context_get_thread_default(), if the thread-default context +is the global default context, this will return that #GMainContext +(with a ref added to it) rather than returning %NULL. + + + the thread-default #GMainContext. Unref + with g_main_context_unref() when you are done with it. + + + + + Returns the currently firing source for this thread. + + + The currently firing source or %NULL. + + + + + Returns the depth of the stack of calls to +g_main_context_dispatch() on any #GMainContext in the current thread. + That is, when called from the toplevel, it gives 0. When +called from within a callback from g_main_context_iteration() +(or g_main_loop_run(), etc.) it returns 1. When called from within +a callback to a recursive call to g_main_context_iteration(), +it returns 2. And so forth. + +This function is useful in a situation like the following: +Imagine an extremely simple "garbage collected" system. + +|[<!-- language="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 g_main_depth() + +|[<!-- language="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 g_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 g_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 + + + + + Allocates @n_bytes bytes of memory. +If @n_bytes is 0 it returns %NULL. + + + 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. + + + 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. + + + 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. + + + 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 interchangeable 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. + + + a pointer to the newly-allocated copy of the memory, or %NULL if @mem + is %NULL. + + + + + 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. + + + + + 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. See the mkdtemp() 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. See the mkdtemp() 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. See the mkstemp() 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. See the mkstemp() 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 @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. + + + + Type of memory chunks to be allocated + + + Number of chunks to be allocated + + + + + 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](glib-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](glib-running.html)). + + + + + + + the program name, needed by gdb for the "[S]tack trace" + option + + + + + + 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 +]| + + + %TRUE if the initialization section should be entered, + %FALSE and blocks otherwise + + + + + location of a static initializable variable + containing 0 + + + + + + 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. + + + + + + + location of a static initializable variable + containing 0 + + + + new non-0 value for *@value_location + + + + + + + + + + + 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. + + + + + + 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 g_strreverse(). This works only if the string +does not contain any multibyte characters. GLib offers the +g_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 g_utf8_strlen()) + + + + the UTF-8 encoded string to match + + + + the reverse of @string or %NULL + + + + + + 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 g_pattern_spec_new() and call +g_pattern_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 +g_pattern_match() instead while supplying the reversed string. + + + %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. + + + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + + + 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. + + + %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. + + + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + + + 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 + + + + + + Outputs a formatted message via the print handler. +The default print handler simply outputs the message to stdout, without +appending a trailing new-line character. Typically, @format should end with +its own new-line character. + +g_print() 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 g_log(), g_log_structured(), or the convenience macros g_message(), +g_warning() and g_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 simply outputs the message to stderr, without appending +a trailing new-line character. Typically, @format should end with its own +new-line character. + +g_printerr() should not be used from within libraries. +Instead g_log() or g_log_structured() should be used, or the convenience +macros g_message(), g_warning() and g_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-precision] + + + + the arguments to insert in the output. + + + + + + Calculates the maximum space needed to store the output +of the sprintf() function. + + + the maximum space needed to store the formatted string + + + + + the format string. See the printf() documentation + + + + the parameters to be inserted into the format string + + + + + + 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 g_ptr_array_find_with_equal_func(). + + + %TRUE if @needle is one of the elements of @haystack + + + + + pointer array to be searched + + + + + + pointer to look for + + + + 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 + + + + + pointer array to be searched + + + + + + 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 + + + + 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 #GPtrArray + + + the index of the pointer to return + + + + + This is just like the standard C qsort() function, but +the comparison routine accepts a user data argument. + +This is guaranteed to be a stable sort since version 2.32. + + + + + + + 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 a unbiased coin toss. + + + + a #GRand + + + + + 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. + + + 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. + + + 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. + + + %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. + + + + + + + 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 + + + + + + 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 +a 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. + + + + + + + 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 g_return_if_fail() +and g_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 + + + + + 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 + + + + + + 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. The program name is found by +taking the last component of @argv[0]. + +Note that for thread-safety reasons this function can only be called once. + + + + + + + the name of the program. + + + + + + Sets the print handler. + +Any messages passed to g_print() will be output via +the new handler. The default handler simply outputs +the message to stdout. By providing your own handler +you can redirect the output, to a GTK+ widget or a +log file for example. + + + the old print handler + + + + + the new print handler + + + + + + Sets the handler for printing error messages. + +Any messages passed to g_printerr() will be output via +the new handler. The default handler simply outputs the +message to stderr. By providing your own handler you can +redirect the output, to a GTK+ widget or a log file for +example. + + + the old error message handler + + + + + the new error message handler + + + + + + 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. 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. 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 slice allocator. +The block address handed out can be expected to be aligned +to at least 1 * sizeof (void*), +though in general slices are 2 * sizeof (void*) bytes aligned, +if a malloc() fallback implementation is used instead, +the alignment may be reduced in a libc dependent fashion. +Note that the underlying slice allocation mechanism can +be changed with the [`G_SLICE=always-malloc`][G_SLICE] +environment variable. + + + 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. Note that the underlying slice allocation +mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] +environment variable. + + + 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. + + + 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. +Note that the underlying slice allocation mechanism can +be changed with the [`G_SLICE=always-malloc`][G_SLICE] +environment variable. + +This can never return %NULL. + + + + 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`][G_DEBUG] environment variable, also see +[`G_SLICE`][G_SLICE] for related debugging options. + +If @mem is %NULL, this macro does nothing. + + + + 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`][G_DEBUG] environment +variable, also see [`G_SLICE`][G_SLICE] for related debugging options. + +If @mem_block is %NULL, this function does nothing. + + + + + + + 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`][G_DEBUG] environment variable, also see +[`G_SLICE`][G_SLICE] for related debugging options. + +If @mem_chain is %NULL, this function does nothing. + + + + 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`][G_DEBUG] environment variable, also see +[`G_SLICE`][G_SLICE] for related debugging options. + +If @mem_chain is %NULL, this function does nothing. + + + + + + + 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. Note that the underlying slice allocation +mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] +environment variable. + +This can never return %NULL as the minimum allocation size from +`sizeof (@type)` is 1 byte. + + + + 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. +Note that the underlying slice allocation mechanism can +be changed with the [`G_SLICE=always-malloc`][G_SLICE] +environment variable. + +This can never return %NULL as the minimum allocation size from +`sizeof (@type)` is 1 byte. + + + + 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 g_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-precision] + + + + the arguments to insert in the output. + + + + + + Removes the source with the given ID from the default main context. You must +use g_source_destroy() for sources added to a non-default main context. + +The ID of a #GSource is given by g_source_get_id(), or will be +returned by the functions g_source_attach(), g_idle_add(), +g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), +g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and +g_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 g_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. + + + For historical reasons, this function always returns %TRUE + + + + + 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. + + + + + The @source_funcs passed to g_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. + + + + + 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 g_idle_add(), g_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 g_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 #GSource 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 + + + + + + See g_spawn_async_with_pipes() for a full description; this function +simply calls the g_spawn_async_with_pipes() without any pipes. + +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 + + + + + + Identical to g_spawn_async_with_pipes() but instead of +creating pipes for the stdin/stdout/stderr, you can pass existing +file descriptors into this function through the @stdin_fd, +@stdout_fd and @stderr_fd parameters. The following @flags +also have their behaviour slightly tweaked as a result: + +%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output +will be discarded, instead of going to the same location as the parent's +standard output. If you use this flag, @standard_output must be -1. +%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error +will be discarded, instead of going to the same location as the parent's +standard error. If you use this flag, @standard_error must be -1. +%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). If you use this flag, @standard_input must be -1. + +It is valid to pass the same fd in multiple parameters (e.g. you can pass +a single fd for both stdout and stderr). + + + %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 + + + + + + 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 + + + + + + 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_STDOUT_TO_DEV_NULL means that the child's standard output +will be discarded, instead of going to the same location as the parent's +standard output. If you use this flag, @standard_output must be %NULL. +%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error +will be discarded, instead of going to the same location as the parent's +standard error. If you use this flag, @standard_error must be %NULL. +%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`). If you use this flag, @standard_input must be %NULL. +%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 @standard_input, @standard_output, @standard_error +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 @standard_input is %NULL, the child's standard input is attached to +`/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set. + +If @standard_error 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 @standard_output 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, @standard_input, @standard_output, +and @standard_error 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 + + + + + + + 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 + + + + + + Set @error if @exit_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 an +exit status for 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 +@exit_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 exit 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 +@exit_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, 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 @exit_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. + + + %TRUE if child exited successfully, %FALSE otherwise (and + @error will be set) + + + + + An exit code 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. @command_line 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 @exit_status is non-%NULL, the platform-specific exit status of +the child is stored there; see the documentation of +g_spawn_check_exit_status() for how to use and interpret this. + +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 exit 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 @exit_status is non-%NULL, the platform-specific exit status of +the child is stored there; see the documentation of +g_spawn_check_exit_status() for how to use and interpret this. +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 @exit_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 + + + + + + + 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 exit 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 g_snprintf(), to avoid the +risk of buffer overflow. + +`glib/gprintf.h` must be explicitly included in order to use this function. + +See also g_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-precision] + + + + the arguments to insert in the output. + + + + + + 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 dest buffer, include the +trailing nul, and return a pointer to the trailing nul byte. +This is useful for concatenating multiple strings together +without having to repeatedly scan for the end. + + + a pointer to trailing nul byte. + + + + + 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 nul-terminated string + + + + the nul-terminated prefix to look for + + + + + + Looks whether the string @str ends with @suffix. + + + %TRUE if @str end with @suffix, %FALSE otherwise. + + + + + a nul-terminated string + + + + the nul-terminated 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 g_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 + + + + %TRUE to accept ASCII alternates + + + + + + 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 + + + + + + Tokenises @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 +g_unichar_isalnum() or g_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 + + + + 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 +|[<!-- language="C" --> + g_ascii_strup (g_strcanon (str, "abc", '?')) +]| + +In order to modify a copy, you may use `g_strdup()`: +|[<!-- language="C" --> + reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); + ... + g_free (reformatted); +]| + + + @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 g_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. + + + + + a string + + + + a 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 g_strchug() and g_strstrip(). + + + @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 g_strchomp() and g_strstrip(). + + + @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 C string or %NULL + + + + another C string or %NULL + + + + + + Replaces all escaped characters with their one byte equivalent. + +This function does the reverse conversion of g_strescape(). + + + 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 +returned string should be freed with g_free() when no longer needed. + +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 +|[<!-- language="C" --> + g_ascii_strup (g_strdelimit (str, "abc", '?')) +]| + +In order to modify a copy, you may use `g_strdup()`: +|[<!-- language="C" --> + reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); + ... + g_free (reformatted); +]| + + + @string + + + + + the string to convert + + + + a string containing the current delimiters, + or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS + + + + the new delimiter character + + + + + + Converts a string to lower case. + This function is totally broken for the reasons discussed +in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() +instead. + + + the string + + + + + the string to convert. + + + + + + Duplicates a string. If @str is %NULL it returns %NULL. +The returned string should be freed with g_free() +when no longer needed. + + + 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 should be freed with g_free() when no +longer needed. + + + a newly-allocated string holding the result + + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + 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 should be freed with g_free() when +no longer needed. + +See also g_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-precision] + + + + the list of parameters to insert into the format string + + + + + + Copies %NULL-terminated array of strings. The copy is a deep copy; +the new array should be freed by first freeing each string, then +the array itself. g_strfreev() does this for you. If called +on a %NULL value, g_strdupv() simply returns %NULL. + + + a new %NULL-terminated array of strings. + + + + + + + a %NULL-terminated array of strings + + + + + + 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. + +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: +|[ + int saved_errno; + + ret = read (blah); + saved_errno = errno; + + g_strerror (saved_errno); +]| + + + a UTF-8 string describing the error code. If the error code + is unknown, it returns a string like "unknown error (<code>)". + + + + + the system error number. See the standard C %errno + documentation + + + + + + Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' +and '"' in the string @source by inserting a '\' before +them. 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 '\' followed by their octal representation. +Characters supplied in @exceptions are not escaped. + +g_strcompress() does the reverse conversion. + + + a newly-allocated copy of @source with certain + characters escaped. See above. + + + + + a string to escape + + + + a string of characters not to escape in @source + + + + + + Frees a %NULL-terminated array of strings, as well as each +string it contains. + +If @str_array is %NULL, this function simply returns. + + + + + + + a %NULL-terminated array of strings to free + + + + + + 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, 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 + + + + + + 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. The returned string +should be freed with g_free(). + + + a newly-allocated string containing all of the strings joined + together, with @separator between them + + + + + a string to insert between each of the + strings, or %NULL + + + + a %NULL-terminated list of strings to join + + + + + + Joins a number of strings together to form one long string, with the +optional @separator inserted between each of them. The returned string +should be freed with g_free(). + +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, or %NULL + + + + a %NULL-terminated 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 g_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, g_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 g_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: g_ascii_strncasecmp(), + which only works on ASCII and is not locale-sensitive, and + g_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. + + + + + a string + + + + a 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. The returned value should be freed when no longer +needed. + +To copy a number of characters from a UTF-8 encoded string, +use g_utf8_strncpy() instead. + + + a newly-allocated buffer containing the first @n bytes + of @str, nul-terminated + + + + + the string to duplicate + + + + the maximum number of bytes to copy from @str + + + + + + Creates a new string @length bytes long filled with @fill_char. +The returned string should be freed when no longer needed. + + + a newly-allocated string filled the @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 +g_utf8_strreverse(). + + + the same pointer passed in as @string + + + + + the string to reverse + + + + + + Searches the string @haystack for the last occurrence +of the string @needle. + + + a pointer to the found occurrence, or + %NULL if not found. + + + + + a nul-terminated string + + + + the nul-terminated 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. + + + a pointer to the found occurrence, or + %NULL if not found. + + + + + a nul-terminated string + + + + the maximum length of @haystack + + + + the nul-terminated string to search for + + + + + + Returns a string describing the given signal, e.g. "Segmentation fault". +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. + + + a UTF-8 string describing the signal. If the signal is unknown, + it returns "unknown signal (<signum>)". + + + + + 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 a +%NULL-terminated vector containing the six strings "", "a", "bc", "", "d" +and "". + +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 a 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 g_strsplit(). + + + a newly-allocated %NULL-terminated array of strings. Use + g_strfreev() to free it. + + + + + + + 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 characters +in @delimiter. A token is the (possibly empty) longest string that does not +contain any of the characters in @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 a +%NULL-terminated vector containing the three strings "abc", "def", +and "ghi". + +The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated +vector containing the four strings "", "def", "ghi", and "". + +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 a 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 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 %NULL-terminated array of strings. Use + g_strfreev() to free it. + + + + + + + The string to be tokenized + + + + A nul-terminated string containing bytes that are used + to split the string. + + + + 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. + + + a pointer to the found occurrence, or + %NULL if not found. + + + + + a string + + + + the maximum length of @haystack. Note that -1 is + a valid length, if @haystack is nul-terminated, meaning it will + search through the whole string. + + + + the string to search for + + + + + + Removes leading and trailing whitespace from a string. +See g_strchomp() and g_strchug(). + + + + a string to remove the leading and trailing whitespace from + + + + + Converts a string to a #gdouble 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 g_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 g_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 #gdouble 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 g_strncasecmp() docs - use g_ascii_strup() + or g_utf8_strup() instead. + + + the string + + + + + the string to convert + + + + + + Checks if @strv contains @str. @strv must not be %NULL. + + + %TRUE if @str is an element of @strv, according to g_str_equal(). + + + + + a %NULL-terminated array of strings + + + + a string + + + + + + Checks if @strv1 and @strv2 contain exactly the same elements in exactly the +same order. Elements are compared using g_str_equal(). To match independently +of order, sort the arrays first (using g_qsort_with_data() or similar). + +Two empty arrays are considered equal. Neither @strv1 not @strv2 may be +%NULL. + + + %TRUE if @strv1 and @strv2 are equal + + + + + a %NULL-terminated array of strings + + + + another %NULL-terminated array of strings + + + + + + + + + + + + Returns the length of the given %NULL-terminated +string array @str_array. @str_array must not be %NULL. + + + length of @str_array. + + + + + a %NULL-terminated array of strings + + + + + + Hook up a new test case at @testpath, similar to g_test_add_func(). +A fixture data structure with setup and teardown functions may be provided, +similar to g_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. + + + + + Create a new test case, similar to g_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 +slash-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 g_test_trap_subprocess(). + +No component of @testpath may start with a dot (`.`) if the +%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to +do so even if it isn’t. + + + + + + + /-separated test case path name for the test. + + + + Test data argument for the test function. + + + + The test function to invoke for this test. + + + + + + Create a new test case, as with g_test_add_data_func(), but freeing +@test_data after the test run is complete. + + + + + + + /-separated test case path name for the test. + + + + Test data argument for the test function. + + + + The test function to invoke for this test. + + + + #GDestroyNotify for @test_data. + + + + + + Create a new test case, similar to g_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 +slash-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 g_test_trap_subprocess(). + +No component of @testpath may start with a dot (`.`) if the +%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to +do so even if it isn’t. + + + + + + + /-separated test case path name for the test. + + + + The test function to invoke for this test. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This function 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 g_test_bug_base() +and @bug_uri_snippet. + +See also: g_test_summary() + + + + + + + Bug specific bug tracker URI portion. + + + + + + Specify the base URI for bug reports. + +The base URI is used to construct bug report messages for +g_test_message() when g_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. + + + + + + + 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 g_build_filename() except +that the first argument has been replaced with a #GTestFileType +argument. + +The data file should either have been distributed with the module +containing the test (%G_TEST_DIST) or built as part of the build +system of that module (%G_TEST_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 +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 g_free() + + + + + the type of file (built vs. distributed) + + + + the first segment of the pathname + + + + %NULL-terminated additional path segments + + + + + + Create a new #GTestCase, named @test_name, this API is fairly +low level, calling g_test_add() or g_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 is used for +multiple tests. In this cases, g_test_create_case() will be +called with the same fixture, but varying @test_name and +@data_test arguments. + + + a newly allocated #GTestCase. + + + + + 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 + + + + + + Create a new test suite with the name @suite_name. + + + A newly allocated #GTestSuite instance. + + + + + a name for the suite + + + + + + 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 (g_log() without +%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging +API. See [Testing for Messages][testing-for-messages]. + +Use g_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 g_test_expect_message().) + +For example: + +|[<!-- language="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 g_error() messages, since +g_error() intentionally never returns even if the program doesn't +abort; use g_test_trap_subprocess() in this case. + +If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly +expected via g_test_expect_message() then they will be ignored. + + + + + + + the log domain of the message + + + + the log level of the message + + + + a glob-style [pattern][glib-Glob-style-pattern-matching] + + + + + + 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. + + + + + + + Returns whether a test has already failed. This will +be the case when g_test_fail(), g_test_incomplete() +or g_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 g_test_build_filename() with two differences. +The first difference is that 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 + + + + + + Get the toplevel test suite for the test path API. + + + the toplevel #GTestSuite + + + + + 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 + + + + + + Initialize the GLib testing framework, e.g. by seeding the +test random number generator, the name for g_get_prgname() +and parsing test related command line args. + +So far, 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 g_test_trap_subprocess() or g_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. + +Options which can be passed to @... are: + + - `"no_g_set_prgname"`: Causes g_test_init() to not call g_set_prgname(). + - %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each + unit test and uses g_set_user_dirs() to set XDG directories to point into + that temporary directory for the duration of the unit test. See the + documentation for %G_TEST_OPTION_ISOLATE_DIRS. + +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 g_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 the main() function. + Changed if any arguments were handled. + + + + Address of the @argv parameter of main(). + Any parameters understood by g_test_init() stripped before return. + + + + %NULL-terminated list of special options, documented below. + + + + + + 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 +g_log_structured() or g_log_structured_array()). To change the fatal +behaviour for specific log messages, programs must install a custom log +writer function using g_log_set_writer_func().See +[Using Structured Logging][using-structured-logging]. + + + + + + + the log handler function. + + + + data passed to the log handler. + + + + + + + + + + + + + + + + + Report 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 + + + + arguments to pass to the printf() function + + + + + + Add a message to the test report. + + + + + + + the format string + + + + printf-like arguments to @format + + + + + + Report 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 + + + + arguments to pass to the printf() function + + + + + + This function enqueus a callback @destroy_func to be executed +during the next test case teardown phase. This is most useful +to auto destruct 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. + + + + + + Enqueue a pointer to be released with g_free() during the next +teardown phase. This is equivalent to calling g_test_queue_destroy() +with a destroy callback of g_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 +g_test_queue_destroy() with a destroy callback of g_object_unref(). + + + + the object to unref + + + + + Get a reproducible random floating point number, +see g_test_rand_int() for details on test case random numbers. + + + a random number from the seeded random number generator. + + + + + Get a reproducible random floating pointer number out of a specified range, +see g_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 + + + + + + Get 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. + + + + + Get a reproducible random integer number out of a specified range, +see g_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 which can be retrieved +with g_test_get_root(). Similar to g_test_run_suite(), the test +cases to be run are filtered according to test path arguments +(`-p testpath` and `-s testpath`) as parsed by g_test_init(). +g_test_run_suite() or g_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 g_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 +g_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 with g_test_skip() and/or + g_test_incomplete() + + + + + Execute the tests within @suite and all nested #GTestSuites. +The test suites to be executed are filtered according to +test path arguments (`-p testpath` and `-s testpath`) as parsed by +g_test_init(). See the g_test_run() documentation for more +information on the order that tests are run in. + +g_test_run_suite() or g_test_run() may only be called once +in a program. + + + 0 on success + + + + + a #GTestSuite + + + + + + Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(), +g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(), +g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), +g_assert_error(), g_test_assert_expected_messages() and the various +g_test_trap_assert_*() macros to not abort to program, but instead +call g_test_fail() and continue. (This also changes the behavior of +g_test_fail() so that it will not cause the test program to abort +after completing the failed test.) + +Note that the g_assert_not_reached() and g_assert() are not +affected by this. + +This function can only be called after g_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 + + + + + + Returns %TRUE (after g_test_init() has been called) if the test +program is running under g_test_trap_subprocess(). + + + %TRUE if the test program is running under +g_test_trap_subprocess(). + + + + + Set the summary for a test, which describes what the test checks, and how it +goes about checking it. 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. + +This should be called at the top of a test function. + +For example: +|[<!-- language="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: g_test_bug() + + + + + + + One or two sentences summarising what the test checks, and how it + checks it. + + + + + + Get the time since the last start of the timer with g_test_timer_start(). + + + the time since the last start of the timer, as a double + + + + + Report the last result of g_test_timer_elapsed(). + + + the last result of g_test_timer_elapsed(), as a double + + + + + Start a timing test. Call g_test_timer_elapsed() when the task is supposed +to be done. Call this function again to restart the timer. + + + + + + + Assert that the stderr output of the last test subprocess +matches @serrpattern. See g_test_trap_subprocess(). + +This is sometimes used to test situations that are formally +considered to be undefined behaviour, like code that hits a +g_assert() or g_error(). In these situations you should skip the +entire test, including the call to g_test_trap_subprocess(), unless +g_test_undefined() returns %TRUE to indicate that undefined +behaviour may be tested. + + + + a glob-style [pattern][glib-Glob-style-pattern-matching] + + + + + Assert that the stderr output of the last test subprocess +does not match @serrpattern. See g_test_trap_subprocess(). + + + + a glob-style [pattern][glib-Glob-style-pattern-matching] + + + + + Assert that the stdout output of the last test subprocess matches +@soutpattern. See g_test_trap_subprocess(). + + + + a glob-style [pattern][glib-Glob-style-pattern-matching] + + + + + Assert that the stdout output of the last test subprocess +does not match @soutpattern. See g_test_trap_subprocess(). + + + + a glob-style [pattern][glib-Glob-style-pattern-matching] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Fork 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 the #GTestTrapFlags 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. + +|[<!-- language="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\n"); + g_printerr ("some stderr text: semagic43\n"); + 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, +and is not always reliable due to problems inherent in +fork-without-exec. Use g_test_trap_subprocess() instead. + + + %TRUE for the forked child and %FALSE for the executing parent process. + + + + + Timeout for the forked test in micro seconds. + + + + Flags to modify forking behaviour. + + + + + + Check the result of the last g_test_trap_subprocess() call. + + + %TRUE if the last test subprocess terminated successfully. + + + + + Check the result of the last g_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 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 g_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 @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 the +#GTestSubprocessFlags flags. + +You can use methods such as g_test_trap_assert_passed(), +g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to +check the results of the subprocess. (But note that +g_test_trap_assert_stdout() and g_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 g_test_subprocess() (after calling +g_test_init()) to see whether you are in a subprocess. + +The following example tests that calling +`my_object_new(1000000)` will abort with an error +message. + +|[<!-- language="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, 0); + g_test_trap_assert_failed (); + g_test_trap_assert_stderr ("*ERROR*too large*"); + } + + int + main (int argc, char **argv) + { + g_test_init (&argc, &argv, NULL); + + g_test_add_func ("/myobject/create_large_object", + test_create_large_object); + return g_test_run (); + } +]| + + + + + + + Test to run in a subprocess + + + + Timeout for the subprocess test in micro seconds. + + + + Flags to modify subprocess behaviour. + + + + + + + + + + + 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 + + + + + + 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 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 + + + + + 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, #G_PRIORITY_DEFAULT. 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 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 [memory management of sources][mainloop-memory-management] 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 +g_timeout_add_seconds() function; this function allows for more +optimizations and more efficient system power usage. + +This internally creates a main loop source using g_timeout_source_new() +and attaches it to the global #GMainContext using g_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 g_get_monotonic_time(). + + + 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, 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). + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +This internally creates a main loop source using g_timeout_source_new() +and attaches it to the global #GMainContext using g_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 g_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 #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + + + + 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 + + + + + + Sets a function to be called at regular intervals with the default +priority, #G_PRIORITY_DEFAULT. 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. + +This internally creates a main loop source using +g_timeout_source_new_seconds() and attaches it to the main loop context +using g_source_attach(). You can do these steps manually if you need +greater control. Also see g_timeout_add_seconds_full(). + +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 g_timeout_add() instead. + +See [memory management of sources][mainloop-memory-management] 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 g_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 %FALSE, at which +point the timeout is automatically destroyed and the function will +not be called again. + +Unlike g_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 [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +If you want timing more precise than whole seconds, use g_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 g_timeout_add_seconds() is preferred over g_timeout_add(). + +This internally creates a main loop source using +g_timeout_source_new_seconds() and attaches it to the main loop context +using g_source_attach(). You can do these steps manually if you need +greater control. + +The interval given is in terms of monotonic time, not wall clock +time. See g_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 #G_PRIORITY_DEFAULT and #G_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, or %NULL + + + + + + Creates a new timeout source. + +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. + +The interval given is in terms of monotonic time, not wall clock +time. See g_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 #GMainContext +and must be added to one with g_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 g_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 0 character 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 g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UCS-4 encoded string + + + + the maximum length (number of characters) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + bytes read, or %NULL. If an error occurs then the index of the invalid + input is stored here. + + + + location to store number + of #gunichar2 written, or %NULL. The value stored here does not include + the trailing 0. + + + + + + Convert a string from a 32-bit fixed width representation as UCS-4. +to UTF-8. The result will be terminated with a 0 byte. + + + a pointer to a newly allocated UTF-8 string. + This value must be freed with g_free(). If an error occurs, + %NULL will be returned and @error set. In that case, @items_read + will be set to the position of the first invalid input character. + + + + + a UCS-4 encoded string + + + + the maximum length (number of characters) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + characters read, or %NULL. + + + + location to store number + of bytes written or %NULL. The value here stored does not include the + trailing 0 byte. + + + + + + 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 hexidecimal 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 + + + + + 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 an 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. 0 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 hexidecimal +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 + + + + + + + + + + + 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 + + + + + + Creates a #GSource to watch for a particular IO condition on a file +descriptor. + +The source will never close the fd -- you must do it yourself. + + + the newly created #GSource + + + + + a file descriptor + + + + IO conditions to watch for on @fd + + + + + + 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. The only supported flag currently is +%FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that +must still be done separately with fcntl(). + +This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if +for fcntl(); these are different on Linux/glibc. + + + %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 a regular +UNIX signal handler; your handler may be invoked while malloc() or +another library function is running, causing reentrancy if you +attempt to use it from the handler. 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 + + + + + + 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 '=' + + + + + + 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. + + + + + + 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 + + + + + + Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include "file", "http", "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. + + + + + + Unescapes a segment of an escaped string. + +If any of the characters in @illegal_characters or the character zero appears +as an escaped character in @escaped_string then that is an error and %NULL +will be returned. This is useful it 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. +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 character zero appears +as an escaped character in @escaped_string then that is an error and %NULL +will be returned. This is useful it 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 g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UTF-16 encoded string + + + + the maximum length (number of #gunichar2) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_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. + + + + location to store number + of characters written, or %NULL. The value stored here does not include + the trailing 0 character. + + + + + + Convert a string from UTF-16 to UTF-8. The result will be +terminated with a 0 byte. + +Note that the input is expected to be already in native endianness, +an initial byte-order-mark character is not handled specially. +g_convert() can be used to convert a byte buffer of UTF-16 data of +ambiguous endianess. + +Further note that this function does not validate the result +string; it may e.g. 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 +things unpaired surrogates. + + + a pointer to a newly allocated UTF-8 string. + This value must be freed with g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UTF-16 encoded string + + + + the maximum length (number of #gunichar2) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_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. + + + + location to store number + of bytes written, or %NULL. The value stored here does not include the + trailing 0 byte. + + + + + + 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][setlocale]. +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. + + + < 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][setlocale]. + + + a newly allocated string. 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][setlocale]. + + + a newly allocated string. 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 or %NULL. + + + + + 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 g_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 g_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 < 0, + 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 g_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 a 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 g_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() 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 g_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 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 g_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 g_strreverse(), this function returns +newly-allocated memory, which should be freed with g_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 < 0, + 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. + + + a newly allocated copy of the requested + substring. Free with g_free() when no longer needed. + + + + + a UTF-8 encoded string + + + + a character offset within @str + + + + another character offset within @str + + + + + + Convert a string from UTF-8 to a 32-bit fixed width +representation as UCS-4. A trailing 0 character 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 g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UTF-8 encoded string + + + + the maximum length of @str to use, in bytes. If @len < 0, + then the string is nul-terminated. + + + + location to store number of + bytes read, or %NULL. + If %NULL, then %G_CONVERT_ERROR_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. + + + + location to store number + of characters written or %NULL. The value here stored does not include + the trailing 0 character. + + + + + + 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 g_utf8_to_ucs4() +but does no error checking on the input. A trailing 0 character +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 g_free(). + + + + + a UTF-8 encoded string + + + + the maximum length of @str to use, in bytes. If @len < 0, + 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 0 character 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 g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UTF-8 encoded string + + + + the maximum length (number of bytes) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_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. + + + + location to store number + of #gunichar2 written, or %NULL. The value stored here does not include + the trailing 0. + + + + + + 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 (i.e. the start of the first invalid +character if some bytes were invalid, or the end of the text +being validated otherwise). + +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 g_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 + + + + + + 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. + + + 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]. + +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 +g_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 g_variant_print()". + + + 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. This call is +equivalent to calling g_variant_type_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 g_variant_type_string_is_valid(). + + + %TRUE if a valid type string was found + + + + + a pointer to any string + + + + the end of @string, or %NULL + + + + location to store the end pointer, or %NULL + + + + + + An implementation of the GNU vasprintf() function which supports +positional parameters, as specified in the Single Unix Specification. +This function is similar to g_vsprintf(), except that it allocates a +string to hold the output, instead of putting the output in a buffer +you allocate in advance. + +`glib/gprintf.h` must be explicitly included in order to use this function. + + + the number of bytes printed. + + + + + the return location for the newly-allocated string. + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + 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-precision] + + + + 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-precision] + + + + 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 g_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-precision] + + + + 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-precision] + + + + the list of arguments to insert in the output. + + + + + + Logs a warning if the expression is not true. + + + + the expression to check + + + + + Internal function used to print messages from the public g_warn_if_reached() +and g_warn_if_fail() macros. + + + + + + + log domain + + + + file containing the warning + + + + line number of the warning + + + + function containing the warning + + + + expression which failed + + + + + + diff --git a/gir-files/GModule-2.0.gir b/gir-files/GModule-2.0.gir new file mode 100644 index 0000000..1e329c1 --- /dev/null +++ b/gir-files/GModule-2.0.gir @@ -0,0 +1,266 @@ + + + + + + + + + The #GModule struct is an opaque data structure to represent a +[dynamically-loaded module][glib-Dynamic-Loading-of-Modules]. +It should only be accessed via the following functions. + + + 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`. + + + 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 + + + + + Opens a module. If the module has already been opened, +its reference count is incremented. + +First of all g_module_open() tries to open @file_name as a module. +If that fails and @file_name has the ".la"-suffix (and is a libtool +archive) it tries to open the corresponding module. If that fails +and it doesn't have the proper module suffix for the platform +(#G_MODULE_SUFFIX), this suffix will be appended and the corresponding +module will be opended. If that fails and @file_name doesn't have the +".la"-suffix, this suffix is appended and g_module_open() tries to open +the corresponding module. If eventually that fails as well, %NULL is +returned. + + + a #GModule on success, or %NULL on failure + + + + + the name of 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 + + + + + + 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`. + + + 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 + + + + + diff --git a/gir-files/GObject-2.0.gir b/gir-files/GObject-2.0.gir new file mode 100644 index 0000000..06856f1 --- /dev/null +++ b/gir-files/GObject-2.0.gir @@ -0,0 +1,17432 @@ + + + + + + + + + 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; + } +]| + +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. It 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 + + + + + + #GBinding is the representation of a binding between a property on a +#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: + +|[<!-- language="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 g_object_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: + +|[<!-- language="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: + +|[<!-- language="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 g_signal_stop_emission() +or g_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 +g_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. + +#GBinding is available since GObject 2.26 + + 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. + + + the source #GObject + + + + + 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. + + + the target #GObject + + + + + 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 you want to hold on to the #GBinding instance +after calling g_binding_unbind(), you will need to hold a reference +to it. + + + + + + + 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 + + + + 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 + + + + + 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(). + + + + 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 marshaller for a #GCClosure with a callback of type +`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter +denotes a flags type. + + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue which can store the returned #gboolean + + + + 2 + + + + a #GValue array holding instance and arg1 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue, which can store the returned string + + + + 3 + + + + a #GValue array holding instance, arg1 and arg2 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gboolean parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GBoxed* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gchar parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gdouble parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the enumeration parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the flags parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gfloat parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gint parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #glong parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GObject* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GParamSpec* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gpointer parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gchar* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #guchar parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #guint parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 3 + + + + a #GValue array holding instance, arg1 and arg2 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gulong parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GVariant* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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 marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 1 + + + + a #GValue array holding only the instance + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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. (See g_closure_set_meta_marshal().) For +GObject's C predefined marshallers (the g_cclosure_marshal_*() +functions), what it provides is a callback function to use instead of +@closure->callback. + + + + + + + a #GClosure + + + + a #GClosureMarshal function + + + + + + Sets the meta marshaller of @closure. A meta marshaller wraps +@closure->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 @closure->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. g_closure_sink() 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(). Ane 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. + + + whether the handler should be called before or after the + default handler of the signal. + + + whether 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: + +|[ +#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 +]| + +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: + +|[ +#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 +]| + +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 types 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: + +|[ +#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 +]| + +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 boxed type implementations, which defines a +type_name_get_type() function registering the boxed type. + + + + 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. + +|[ +G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, + gtk_gadget, + GTK_TYPE_THING, + 0, + G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, + gtk_gadget_gizmo_init)); +]| +expands to +|[ +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 #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 0 +(%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 0 +(%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 volatile gsize g_define_type_id__volatile = 0; + if (g_once_init_enter (&g_define_type_id__volatile)) + { + 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 (&g_define_type_id__volatile, g_define_type_id); + } + return g_define_type_id__volatile; +} +]| +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 #GValue structure. + + + + A #GValue structure. + + + + + All the fields in the GInitiallyUnowned structure +are private to the #GInitiallyUnowned implementation and should never be +accessed directly. + + + + + + + + + + + + + The class structure for the GInitiallyUnowned type. + + + the parent class + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GObject + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + All the fields in the GObject structure are private +to the #GObject implementation and should never be accessed directly. + + + 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. + +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + 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: + +|[ + 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. + +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, 0) +- object-signal, object_signal: equivalent to g_signal_connect_object (..., 0) +- 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) + +|[<!-- language="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); +]| + + + @object + + + + + 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 + + + + + + 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; + gchar *strval; + GObject *objval; + + g_object_get (my_object, + "int-property", &intval, + "str-property", &strval, + "obj-property", &objval, + NULL); + + // Do something with intval, 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" --> + enum + { + PROP_0, + PROP_FOO, + PROP_LAST + }; + + static GParamSpec *properties[PROP_LAST]; + + static void + my_object_class_init (MyObjectClass *klass) + { + properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", + 0, 100, + 50, + G_PARAM_READWRITE); + 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. + + + + + + + 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 + + + + + + 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. + +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 (retrived 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"); + // retrive 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 + + + + + + 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 finalized. 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][canonical-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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GObject + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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" --> +enum { + PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES +}; + +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", "Foo", "Foo", + -1, G_MAXINT, + 0, + G_PARAM_READWRITE); + + obj_properties[PROP_BAR] = + g_param_spec_string ("bar", "Bar", "Bar", + NULL, + G_PARAM_READWRITE); + + gobject_class->set_property = my_object_set_property; + gobject_class->get_property = my_object_get_property; + g_object_class_install_properties (gobject_class, + N_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. + +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 + + + the parameter can only be set upon object construction + + + 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 is an object structure that encapsulates the metadata +required to specify parameters, such as e.g. #GObject properties. + +## Parameter names # {#canonical-parameter-names} + +Parameter names need to start with a letter (a-z or A-Z). +Subsequent characters can be letters, numbers or a '-'. +All other characters are replaced by a '-' during construction. +The result of this replacement is called the canonical name of +the parameter. + + + Creates a new #GParamSpec instance. + +A property name consists of segments consisting of ASCII letters and +digits, separated by either the '-' or '_' character. The first +character of a property name must be a letter. Names which violate these +rules lead to undefined behaviour. + +When creating and looking up a #GParamSpec, either separator can be +used, but they cannot be mixed. Using '-' is considerably more +efficient and in fact required when using property names as detail +strings for signals. + +Beyond the name, #GParamSpecs have two more descriptive +strings associated with them, the @nick, which should be suitable +for use as a label for the property in a property editor, and the +@blurb, which should be a somewhat longer description, suitable for +e.g. a tooltip. The @nick and @blurb should ideally be localized. + + + a newly allocated #GParamSpec instance + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + This is a type of #GParamSpec type that simply redirects operations to +another paramspec. 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 overidden +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. + + + 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. + + + + + + + + + + + + + + + + + The #GType of values conforming to this #GParamSpec + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 %FALSE means to abort the + current emission and %TRUE is returned for continuation. + + + + + 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. This +allows 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, the overall +signal description outlines how especially the RUN flags control the +stages of a signal emission. + + + 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. Since 2.30. + + + 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. Since 2.32. + + + + 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. + + + + + 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 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 matched. + + + + A structure holding in-depth information for a specific signal. It is +filled in by the g_signal_query() function. + + + 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); + ]| + + + + + + + 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 #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 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 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 g_value_init(). +That is, this macro checks whether this type provides an implementation +of the #GTypeValueTable functions required for a type to create a #GValue of. + + + + A #GType value. + + + + + 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 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. + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + This is a convenience function often needed in class initializers. +It returns the class structure of the immediate parent type of the +class passed in. Since derived classes hold a reference count 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. + + + + + + + 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. + + + + + + + a #GTypeClass structure to unref + + + + + + + + + + + + + + + + + + + + This function is essentially the same as g_type_class_ref(), +except that the classes reference count isn't incremented. +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. + + + 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. + + + 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() + + + + Bit masks used to check or determine specific characteristics of a +fundamental type. + + + Indicates a classed type + + + Indicates an instantiable 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 + inititalization 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, it is ignored, since instances are allocated with the [slice allocator][glib-Memory-Slices] now. + + + + 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 #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 g_type_module_register_type() and g_type_module_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 +unref cannot happen in 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 +g_type_module_use() and g_type_module_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. + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The GObject type system supports dynamic loading of types. +The #GTypePlugin interface is used to handle the lifecycle +of dynamically loaded 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: + |[<!-- language="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 + g_type_class_ref() or through g_type_create_instance() (this is + being called by g_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 g_type_plugin_use() and g_type_plugin_complete_type_info() + on @new_type_plugin. + +4. At some point the type's implementation isn't required anymore, + e.g. after g_type_class_unref() or g_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 g_type_plugin_complete_type_info() and then it calls + g_type_plugin_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 +g_type_plugin_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 +g_type_plugin_use() and g_type_plugin_complete_type_info() again +when the type is needed again. + +#GTypeModule 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 instantiable 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 instantiable 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. +It is filled in by the g_type_query() function. + + + the #GType value of the type + + + + the name of the type + + + + the size of the class structure + + + + the size of the instance structure + + + + + The #GTypeValueTable provides the functions required by the #GValue +implementation, to serve as a container for values of a type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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: + - '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'. + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + Checks if @value holds (or contains) a value of @type. +This macro will also check for @value != %NULL and issue a +warning if the check fails. + + + + A #GValue structure. + + + A #GType value. + + + + + 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 + + + + + If passed to G_VALUE_COLLECT(), allocated data won't be copied +but used verbatim. This does not affect ref-counted types like +objects. + + + + + Get the type identifier of @value. + + + + A #GValue structure. + + + + + Gets the type name of @value. + + + + A #GValue 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. +The data within the structure has protected scope: it is accessible only +to functions within a #GTypeValueTable structure, or implementations of +the g_value_*() API. That is, code portions which implement 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 G_VALUE_TYPE() macro. + + + + + + + + + + + Copies the value of @src_value into @dest_value. + + + + + + + An initialized #GValue structure. + + + + An initialized #GValue 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. + + + + + An initialized #GValue 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 with the default value of @type. + + + the #GValue structure that has been passed in + + + + + A zero-filled (uninitialized) #GValue structure. + + + + Type the #GValue should hold values of. + + + + + + Initializes and sets @value from an instantiatable type via the +value_table's collect_value() function. + +Note: The @value will be initialised with the exact type of +@instance. If you wish to set the @value's type to a different GType +(such as a parent class GType), you need to manually call +g_value_init() and g_value_set_instance(). + + + + + + + An uninitialized #GValue structure. + + + + the instance + + + + + + Returns the value contents as pointer. This function asserts that +g_value_fits_pointer() returned %TRUE for the passed in value. +This is an internal function introduced mainly for C marshallers. + + + the value contents as pointer + + + + + An initialized #GValue structure + + + + + + Clears the current value in @value and resets it to the default value +(as if the value had just been initialized). + + + the #GValue structure that has been passed in + + + + + An initialized #GValue 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 + + + + boxed value to be set + + + + + + 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 via the +value_table's collect_value() function. + + + + + + + An initialized #GValue 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_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. + + + + + + + a valid #GValue of type %G_TYPE_STRING + + + + static string to be set + + + + + + Set the contents of a %G_TYPE_STRING #GValue to @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 + + + + + + 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, e.g. to transform a %G_TYPE_INT value +into a %G_TYPE_FLOAT value. Performing transformations between +value types might incur precision lossage. Especially +transformations into strings might reveal seemingly arbitrary +results and shouldn't be relied upon for production code (such +as rcfile value or object property serialization). + + + Whether a transformation rule was found and could be applied. + Upon failing transformations, @dest_value is left untouched. + + + + + Source value. + + + + Target value. + + + + + + Clears the current value in @value (if any) and "unsets" the type, +this releases all resources associated with this GValue. An unset +value is the same as an uninitialized (zero-filled) #GValue +structure. + + + + + + + An initialized #GValue structure. + + + + + + Registers a value transformation function for use in g_value_transform(). +A 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 value of type @dest_type + + + + + + Returns whether a #GValue of type @src_type can be copied into +a #GValue of type @dest_type. + + + %TRUE if g_value_copy() is possible with @src_type and @dest_type. + + + + + source type to be copied. + + + + destination type for copying. + + + + + + Check whether g_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. + + + %TRUE if the transformation is possible, %FALSE otherwise. + + + + + Source type. + + + + Target type. + + + + + + + A #GValueArray contains an array of #GValue elements. + + + 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_ containd 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 +g_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 +finalized 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. + + + + + + + data that was provided when the weak reference was established + + + + the object being finalized + + + + + + A structure containing a weak reference to a #GObject. It 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, any #GWeakRefs taken +before it was disposed will continue to point to %NULL. If +#GWeakRefs are taken after the object is disposed and +re-referenced, they will continue to point to it until its refcount +goes back to zero, at which point they too will be invalidated. + + + + + + + + + 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. + + + 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 marshaller for a #GCClosure with a callback of type +`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter +denotes a flags type. + + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue which can store the returned #gboolean + + + + 2 + + + + a #GValue array holding instance and arg1 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue, which can store the returned string + + + + 3 + + + + a #GValue array holding instance, arg1 and arg2 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gboolean parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GBoxed* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gchar parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gdouble parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the enumeration parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the flags parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gfloat parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gint parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #glong parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GObject* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GParamSpec* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gpointer parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gchar* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #guchar parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #guint parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 3 + + + + a #GValue array holding instance, arg1 and arg2 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gulong parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GVariant* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer user_data)`. + + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 1 + + + + a #GValue array holding only the instance + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + 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. + +A macro is also included that allows this function to be used without +pointer casts. + + + + + + + A pointer to a handler ID (of type #gulong) of the handler to be disconnected. + + + + The instance to remove the signal handler from. + + + + + + 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 #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. + + + + + + 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 + + + + souce #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 + + + + + + Sets @value to its default value as specified in @pspec. + + + + + + + a valid #GParamSpec + + + + a #GValue of correct type for @pspec + + + + + + 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. + +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 it, 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 +automaticaly 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. + +@weak_pointer_location 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 #GCallback function to a signal for a particular object. + +The handler will be called before the default handler of the signal. + +See [memory management of signal handlers][signal-memory-management] for +details on how to handle the return value and memory management of @data. + + + + 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 after the default handler of the signal. + + + + 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. + + + the handler ID (always greater than 0 for successful connections) + + + + + 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. + + + the handler ID (always greater than 0 for successful connections) + + + + + 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. + + + the handler ID (always greater than 0 for successful connections) + + + + + 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). + + + 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); +]| + + + + 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. + +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. + +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. + + + + + + Emits a signal. + +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. + +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. + + + + + 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 deactive 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 an OR-ed combination of #GSignalMatchType +flags, and the criteria values are passed as arguments. +Passing at least one of the %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. + + + 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 an OR-ed +combination of #GSignalMatchType flags, and the criteria values are +passed as arguments. Passing at least one of the +%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. + + + 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 an OR-ed combination of +#GSignalMatchType flags, and the criteria values are passed as arguments. +Passing at least one of the %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. + + + 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. + + + + + + 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. + +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 of the GSignal system. + +When registering a signal and looking up a signal, either separator can +be used, but they cannot be mixed. + +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 overriden 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 + + + + + + + + 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 an 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 the dynamic @interface_type to @instantiable_type. The information +contained in the #GTypePlugin structure pointed to by @plugin +is used to manage the relationship. + + + + + + + #GType value of an instantiable type + + + + #GType value of an interface type + + + + #GTypePlugin structure to retrieve the #GInterfaceInfo from + + + + + + Adds the static @interface_type to @instantiable_type. +The information contained in the #GInterfaceInfo structure +pointed to by @info is used to manage the relationship. + + + + + + + #GType value of an instantiable 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 + + + + + + + + + + + + + + + + + + + + This function is essentially the same as g_type_class_ref(), +except that the classes reference count isn't incremented. +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. + + + 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 +implementators 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 + + + + + + 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 initalized 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. + + + 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. + + + + + + + the default vtable + structure for a 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 #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 anchestry for + + + + possible anchestor 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 +anchestry, 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 anchestor 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. + + + + + + + #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 g_value_transform(). +A 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 value of type @dest_type + + + + + + Returns whether a #GValue of type @src_type can be copied into +a #GValue of type @dest_type. + + + %TRUE if g_value_copy() is possible with @src_type and @dest_type. + + + + + source type to be copied. + + + + destination type for copying. + + + + + + Check whether g_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. + + + %TRUE if the transformation is possible, %FALSE otherwise. + + + + + Source type. + + + + Target type. + + + + + + diff --git a/gir-files/Gdk-3.0.gir b/gir-files/Gdk-3.0.gir new file mode 100644 index 0000000..05a5eae --- /dev/null +++ b/gir-files/Gdk-3.0.gir @@ -0,0 +1,27088 @@ + + + + + + + + + + + + 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(). + +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 + + + + + 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" + + + 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 + + + %TRUE if the event contains smooth scroll information + + + + + a #GdkEvent + + + + return location for X delta + + + + return location for Y delta + + + + + + Extracts the scroll direction from an event. + + + %TRUE if the event delivered a scroll direction + + + + + 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 + + + + 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 + + + + + + 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 + + + + + + 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. + + + + + + + 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 + + + + + + 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. + + + + + + + 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. + + + + + + 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. + + + + + + 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.) + + + 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 + + + + + + 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+ + + + + + + + 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 + + + + + + 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 + + + + + + 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(). + + + + + + + + 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 + + + + + + diff --git a/gir-files/Gdk-4.0.gir b/gir-files/Gdk-4.0.gir new file mode 100644 index 0000000..02f5129 --- /dev/null +++ b/gir-files/Gdk-4.0.gir @@ -0,0 +1,22634 @@ + + + + + + + + + + + + An opaque type representing a string as an index into a table +of strings on the X server. + + + + + Defines all possible DND actions. This can be used in 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 + + + + 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_display (display); +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); +]| + + 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 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 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 + + + + + + + + + + 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 + + + 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. + + + + + 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. + + + + + #GdkCairoContext is an object representing the platform-specific +draw context. + +#GdkCairoContexts are created for a #GdkDisplay using +gdk_surface_create_cairo_context(), and the context can then be used +to draw on that #GdkSurface. + + Retrieves a Cairo context to be used to draw on the #GdkSurface +of @context. A call to gdk_draw_context_begin_frame() with this +@context must have been done or this function will return %NULL. + +The returned context is guaranteed to be valid until +gdk_draw_context_end_frame() is called. + + + a Cairo context to be used + to draw the contents of the #GdkSurface. %NULL is returned + when @contet is not drawing. + + + + + a #GdkCairoContext that is currently drawing + + + + + + + The #GdkClipboard object represents a clipboard of data shared +between different applications or between different parts of +the same application. + +To get a GdkClipboard object, use gdk_display_get_clipboard() or +gdk_display_get_primary_clipboard(). You can find out about the data that +is currently available in a clipboard using gdk_clipboard_get_formats(). + +To make text or image data available in a clipboard, use gdk_clipboard_set_text() or +gdk_clipboard_set_texture(). For other data, you can use gdk_clipboard_set_content(), +which takes a #GdkContentProvider object. + +To read textual or image data from a clipboard, use gdk_clipboard_read_text_async() or +gdk_clipboard_read_texture_async(). For other data, use 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 or %NULL + 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 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. When the operation is finished @callback will be called. +You can then call gdk_clipboard_read_finish() to get the result of the +operation. + +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][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 + + + + + + Finishes an asynchronous clipboard read started with gdk_clipboard_read_async(). + + + a #GInputStream or %NULL on error. + + + + + a #GdkClipboard + + + + a #GAsyncResult + + + + pointer to store + the chosen mime type in or %NULL + + + + + + Asynchronously request the @clipboard contents converted to a string. +When the operation is finished @callback will be called. You can then +call gdk_clipboard_read_text_finish() to get the result. + +This is a simple wrapper around gdk_clipboard_read_value_async(). Use +that function or 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 started with +gdk_clipboard_read_text_async(). + + + a new string or %NULL on error. + + + + + a #GdkClipboard + + + + a #GAsyncResult + + + + + + Asynchronously request the @clipboard contents converted to a #GdkPixbuf. +When the operation is finished @callback will be called. You can then +call gdk_clipboard_read_texture_finish() to get the result. + +This is a simple wrapper around gdk_clipboard_read_value_async(). Use +that function or 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 started with +gdk_clipboard_read_texture_async(). + + + a new #GdkTexture or %NULL on error. + + + + + a #GdkClipboard + + + + a #GAsyncResult + + + + + + Asynchronously request the @clipboard contents converted to the given +@type. When the operation is finished @callback will be called. +You can then call gdk_clipboard_read_value_finish() to get the resulting +#GValue. + +For local clipboard contents that are available in the given #GType, the +value will be copied directly. Otherwise, GDK will try to use +gdk_content_deserialize_async() to convert the clipboard's data. + + + + + + + a #GdkClipboard + + + + a #GType to read + + + + the [I/O priority][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 + + + + + + Finishes an asynchronous clipboard read started with +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. + + + + + + + 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 to +preserve them for later usage. If the clipboard is not local, this function +does nothing but report success. + +This function is called automatically when gtk_main() or #GtkApplication +exit, so you likely don't need to call it. + + + + + + + a #GdkClipboard + + + + the [I/O priority][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 + + + + + + Finishes an asynchronous clipboard store started with 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. + + + + The ::changed signal is emitted when the clipboard changes ownership. + + + + + + + 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 + + + + + + A GdkContentDeserializer is used to deserialize content received via +inter-application data transfers. + + + Gets the cancellable that was passed to 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 that was passed to 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 io priority that was passed to gdk_content_deserialize_async(). + + + the io priority for the current operation + + + + + a #GdkContentDeserializer + + + + + + Gets the data that was associated with @deserializer via gdk_content_deserializer_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 + + + + + + + This section describes the #GdkContentFormats structure that is used to +advertise and negotiate the format of content passed between different +widgets, windows or applications using for example the clipboard or +drag'n'drop. + +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. + +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 gdk_content_formats_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 gdk_content_formats_to_string() exists. +It will print a comma-seperated formats 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 #GdkContentFormatsBuilder 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 #GdkContentFormatsBuilder 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 #GTypes included in @formats. Note that @formats may not +contain any #GTypes, in particular when they are empty. In that +case %NULL will be returned. + + + %G_TYPE_INVALID-terminated array of + types included in @formats or %NULL if none. + + + + + a #GdkContentFormats + + + + optional pointer to take the + number of #GTypes 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 or %NULL + if none. + + + + + + + a #GdkContentFormats + + + + optional pointer to take the + number of mime types contained in the return value + + + + + + 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. +This is meant for debugging and logging. + +The form of the representation may change at any time and is +not guranteed to stay identical. + + + + + + + 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. +This is a small wrapper around gdk_content_formats_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 + + + + + + + A #GdkContentFormatsBuilder struct is an opaque struct. It is meant to +not be kept around and only be used to create new #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 @gtype to @builder if it has not already been added. + + + + + + + a #GdkContentFormatsBuilder + + + + 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 +gdk_content_formats_builder_free_to_formats(). + + + the newly created #GdkContentFormats + with all the formats added to @builder + + + + + a #GdkContentFormatsBuilder + + + + + + Releases a reference on the given @builder. + + + + + + + a #GdkContentFormatsBuilder + + + + + + + A GdkContentProvider is used to provide content for the clipboard in +a number of formats. + +To create a GdkContentProvider, use gdk_content_provider_new_for_value() or +gdk_content_provider_new_for_bytes(). + +GDK knows how to handle common text and image formats out-of-the-box. See +#GdkContentSerializer and #GdkContentDeserializer 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 + + + + + + + + + + + + + + + + + + + + Emits the #GdkContentProvider::contents-changed signal. + + + + + + + a #GdkContentProvider + + + + + + + + + + + + + + + + + + + + Gets the convtents 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 gdk_content_provider_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 gdk_content_provider_ref_formats(). + + + The storable formats of the provider + + + + + a #GdkContentProvider + + + + + + Asynchronously writes the contents of @provider to @stream in the given +@mime_type. When the operation is finished @callback will be called. You +can then call gdk_content_provider_write_mime_type_finish() to get the +result of the operation. + +The given mime type does not need to be listed in the formats returned by +gdk_content_provider_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 + + + + the [I/O priority][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 + + + + + + Finishes an asynchronous write operation started with +gdk_content_provider_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 #GdkContentProvider::contents-changed signal. + + + + + + + a #GdkContentProvider + + + + + + Gets the convtents 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 gdk_content_provider_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 gdk_content_provider_ref_formats(). + + + The storable formats of the provider + + + + + a #GdkContentProvider + + + + + + Asynchronously writes the contents of @provider to @stream in the given +@mime_type. When the operation is finished @callback will be called. You +can then call gdk_content_provider_write_mime_type_finish() to get the +result of the operation. + +The given mime type does not need to be listed in the formats returned by +gdk_content_provider_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 + + + + the [I/O priority][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 + + + + + + Finishes an asynchronous write operation started with +gdk_content_provider_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. + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + the [I/O priority][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 + + + + + + + + + + %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 + + + + + + A GdkContentSerializer is used to serialize content for inter-application +data transfers. + + + Gets the cancellable that was passed to gdk_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 that was passed to gdk_content_serialize_async(). + + + the output stream for the current operation + + + + + a #GdkContentSerializer + + + + + + Gets the io priority that was passed to gdk_content_serialize_async(). + + + the io priority for the current operation + + + + + a #GdkContentSerializer + + + + + + Gets the data that was associated with @serializer via gdk_content_serializer_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 + + + + + + + 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. + + + + A #GdkCursor represents a cursor. Its contents are private. + +Cursors are immutable objects, so they can not change after +they have been constructed. + + 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" + + + 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 + + + + %NULL or 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. + + + 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. + + + 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 and the GdkCursor::texture property will be set. + + + 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 and the GdkCursor::name property will be set. + + + the texture for cursor or %NULL if it is a + named cursor + + + + + a #GdkCursor. + + + + + + + + + + + + + + + + + + + + + + The #GdkDevice object represents a single input device, such +as a keyboard, a mouse, a touchpad, etc. + +See the #GdkSeat 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. + + + + + + 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 + + + + + + name of the 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_surface_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 surface 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 surface 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 surfaces. + + + the last surface 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 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 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 @surface. 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 #GdkSurface. + + + + an array of doubles to store the values of +the axes of @device in, or %NULL. + + + + + + location to store the modifiers, or %NULL. + + + + + + Obtains the surface underneath @device, returning the location of the device in @win_x and @win_y in +double precision. Returns %NULL if the surface 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 #GdkSurface 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 surface origin, or %NULL. + + + + return location for the Y coordinate of the device location, + relative to the surface origin, 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 + + + + + + Returns a #GList of #GdkAtoms, containing the labels for +the axes that @device currently has. + + + + A #GList of strings, 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 surface. + +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. + + + + + + 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 #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 + + + + + + + #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. + + 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 seat. + + + + GdkDisplay objects are the GDK 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 #GdkSeat +objects. Every display has a one or more seats, which can be accessed with +gdk_display_get_default_seat() and gdk_display_list_seats(). + +Output devices are represented by #GdkMonitor objects, which can be accessed +with gdk_display_get_monitor() 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. + + + a #GdkDisplay, or %NULL if the + display could not be opened + + + + + 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, +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 + + + + + + Gets the clipboard used for copy/paste operations. + + + the display's clipboard + + + + + a #GdkDisplay + + + + + + Returns the default group leader surface for all toplevel surfaces +on @display. This surface is implicitly created by GDK. +See gdk_surface_set_group(). + + + The default group leader surface +for @display + + + + + a #GdkDisplay + + + + + + Returns the default #GdkSeat for this display. + + + the default seat. + + + + + 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 + + + + + a #GdkDisplay + + + + + + Returns the #GdkKeymap attached to @display. + + + the #GdkKeymap attached to @display. + + + + + the #GdkDisplay + + + + + + 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 @surface +resides, or a monitor close to @surface if it is outside +of all monitors. + + + the monitor with the largest overlap with @surface + + + + + a #GdkDisplay + + + + a #GdkSurface + + + + + + 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 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 + + + + + + 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. To make sure there is a dedicated +primary monitor, use gdk_monitor_is_primary() on the returned monitor. + + + the primary monitor, or any monitor if no + primary monitor is configured by the user + + + + + 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, or %NULL + + + + + a #GdkDisplay + + + + + + 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 + + + + + + Returns whether surfaces can reasonably be expected to have +their alpha channel drawn correctly on the screen. Check +gdk_display_is_rgba() for wether 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 wether 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 gdk_display_is_composited() +to check if that is the case. + +For setting an overall opacity for a top-level surface, see +gdk_surface_set_opacity(). + +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 + + + + + + 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.) + + + the first #GdkEvent on the + event queue + + + + + a #GdkDisplay + + + + + + Appends a copy of the given event onto the front of the event +queue for @display. + + + + + + + a #GdkDisplay + + + + a #GdkEvent. + + + + + + Returns %TRUE if gdk_surface_input_shape_combine_mask() can +be used to modify the input shape of surfaces on @display. + + + %TRUE if surfaces with modified input shape are supported + + + + + a #GdkDisplay + + + + + + Returns %TRUE if gdk_surface_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 + + + + + + %TRUE if the display properly composits the alpha channel. +See gdk_display_is_composited() for details. + + + + %TRUE if the display supports an alpha channel. See gdk_display_is_rgba() +for details. + + + + 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 ::setting-changed signal is emitted whenever a setting +changes its value. + + + + + + the name of the setting that changed + + + + + + + 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 + + + + + + + The GdkDrag struct contains only private fields and +should not be accessed directly. + + Starts a drag and creates a new drag context for it. + +This function is called by the drag source. + + + a newly created #GdkDrag or + %NULL on error. + + + + + 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 + + + + + + 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 +@drag. + +The #GdkDrag 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 #GdkDrag + + + + whether the drag was ultimatively successful + + + + + + Determines the bitmask of possible actions proposed by the source. + + + the #GdkDragAction flags + + + + + 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, or %NULL + + + + + 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 + + + + + + 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 #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 drag operation was cancelled. + + + + + + The reason the drag was cancelled + + + + + + The drag operation was finished, the destination +finished reading all data. The drag object can now +free all miscellaneous data. + + + + + + The drag operation was performed on an accepting client. + + + + + + + Used in #GdkDrag to indicate what the destination +should do with the dropped data. + + 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. + + + Ask the user what to do with the data. + + + Checks if @action represents a single action or if it +includes multiple flags that can be selected from. + +When @action is 0 - 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. + + + + #GdkDrawContext is the base object used by contexts implementing different +rendering methods, such as #GdkGLContext or #GdkVulkanContext. It provides +shared functionality between those contexts. + +You will always interact with one of those s.ubclasses. + +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 #GdkCairoContext and a #GdkGLContext need to be treated +differently. + +A call to this function is a requirement for drawing and must be followed +by a call to gdk_draw_context_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 gdk_draw_context_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 #GskRenderers, so application code does not need to call these +functions explicitly. + + + + + + + the context used to draw the frame + + + + minimum region that should be drawn + + + + + + Ends a drawing operation started with gdk_draw_context_begin_frame() +and makes the drawing available on screen. See that function for more +details about drawing. + +When using a #GdkGLContext, this function may call `glFlush()` +implicitly before returning; it is not recommended to call `glFlush()` +explicitly before calling this function. + + + + + + + a #GdkDrawContext + + + + + + Retrieves the #GdkDisplay the @context is created for + + + a #GdkDisplay or %NULL + + + + + a #GdkDrawContext + + + + + + Retrieves the region that is currently in the process of being repainted. + +After a call to gdk_draw_context_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 inbetween calls to gdk_draw_context_begin_frame() and +gdk_draw_context_end_frame(), %NULL will be returned. + + + a Cairo region or %NULL if not drawing + a frame. + + + + + a #GdkDrawContext + + + + + + Retrieves the #GdkSurface used by the @context. + + + a #GdkSurface or %NULL + + + + + a #GdkDrawContext + + + + + + Returns %TRUE if @context is in the process of drawing to its surface +after a call to gdk_draw_context_begin_frame() and not yet having called +gdk_draw_context_end_frame(). +In this situation, drawing commands may be effecting the contents of a +@context's surface. + + + %TRUE if the context is between begin_frame() and end_frame() calls. + + + + + a #GdkDrawContext + + + + + + The #GdkDisplay used to create the #GdkDrawContext. + + + + The #GdkSurface the gl context is bound to. + + + + + + + + The GdkDrop struct contains only private fields and +should not be accessed directly. + + Ends the drag operation after a drop. + +The @action must be a single action selected from the actions +available via gdk_drop_get_actions(). + + + + + + + a #GdkDrop + + + + the action performed by the destination or 0 if the drop + failed + + + + + + Returns the possible actions for this #GdkDrop. If this value +contains multiple actions - ie gdk_drag_action_is_unique() +returns %FALSE for the result - gdk_drag_finish() must choose +the action to use when accepting the drop. + +This value may change over the lifetime of the #GdkDrop both +as a response to source side actions as well as to calls to +gdk_drop_status() or gdk_drag_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 io priority for the read operation + + + + optional #GCancellable object, + %NULL to ignore + + + + a #GAsyncReadyCallback to call when + the request is satisfied + + + + the data to pass to @callback + + + + + + Finishes an async drop read operation, see gdk_drop_read_async(). + + + the #GInputStream, or %NULL + + + + + a #GdkDrop + + + + a #GAsyncResult + + + + return location for the used mime type + + + + + + Asynchronously request the drag operation's contents converted to a string. +When the operation is finished @callback will be called. You can then +call gdk_drop_read_text_finish() to get the result. + +This is a simple wrapper around gdk_drop_read_value_async(). Use +that function or gdk_drop_read_async() directly if you need more +control over the operation. + + + + + + + a #GdkDrop + + + + optional #GCancellable object, %NULL to ignore. + + + + callback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finishes an asynchronous read started with +gdk_drop_read_text_async(). + + + a new string or %NULL on error. + + + + + a #GdkDrop + + + + a #GAsyncResult + + + + + + Asynchronously request the drag operation's contents converted to the given +@type. When the operation is finished @callback will be called. +You can then call gdk_drop_read_value_finish() to get the resulting +#GValue. + +For local drag'n'drop operations that are available in the given #GType, the +value will be copied directly. Otherwise, GDK will try to use +gdk_content_deserialize_async() to convert the data. + + + + + + + a #GdkDrop + + + + a #GType to read + + + + the [I/O priority][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 + + + + + + Finishes an async drop read started with +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 gdk_drop_get_actions(). Those actions may +change in the future, even depending on the actions you provide here. + +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 0 to indicate + that a drop will not be accepted + + + + + + 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. + + + + + The GdkEvent struct contains only private fields and +should not be accessed directly. + + Creates a new event of the given type. All fields are set to 0. + + + a newly-allocated #GdkEvent. Free with g_object_unref() + + + + + 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. #GdkSurface’s and strings). + + + a copy of @event. Free with g_object_unref() + + + + + a #GdkEvent + + + + + + Extracts all axis values from an event. + + + %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. + + + %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 surface relative x/y coordinates from an event. + + + %TRUE if the event delivered event surface coordinates + + + + + a #GdkEvent + + + + location to put event surface x coordinate + + + + location to put event surface y coordinate + + + + + + Extracts the crossing detail from an event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + return location for the crossing detail + + + + + + Extracts the crossing mode from an event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + return location for the crossing mode + + + + + + 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 + + + + + + Retrieves the #GdkDisplay associated to the @event. + + + a #GdkDisplay + + + + + a #GdkEvent + + + + + + Gets the #GdkDrop from a DND event. + + + the drop + + + + + 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 whether this is a focus-in or focus-out event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + return location for focus direction + + + + + + Extracts the grab surface from a grab broken event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + Return location for the grab surface + + + + + + Extracts the key group from an event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + return location for the key group + + + + + + Extracts whether the event is a key event for +a modifier key. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + return location for the value + + + + + + 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 + + + + + + Retrieves the history of the @event motion, as a list of time and +coordinates. + + + a list + of time and coordinates + + + + + + + a #GdkEvent of type %GDK_MOTION_NOTIFY + + + + + + Extracts the information from a pad event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + Return location for the axis index + + + + Return location for the axis value + + + + + + Extracts information about the pressed button from +a pad event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + Return location for the button + + + + + + Extracts group and mode information from a pad event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + return location for the group + + + + return location for the mode + + + + + + 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 + + + + + a #GdkEvent + + + + + + 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 + + + + + + Retrieves the scroll deltas from a #GdkEvent + + + %TRUE if the event contains smooth scroll information + + + + + a #GdkEvent + + + + return location for X delta + + + + return location for Y delta + + + + + + Extracts the scroll direction from an event. + + + %TRUE if the event delivered a scroll direction + + + + + 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 #GdkSurface 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). +@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 + + + + + + Extracts the #GdkSurface associated with an event. + + + The #GdkSurface associated with the event + + + + + a #GdkEvent + + + + + + 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 whether a touch event is emulating a pointer event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + Return location for information + + + + + + Extracts the angle from a touchpad event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + Return location for angle + + + + + + Extracts delta information from a touchpad event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + return location for x + + + + return location for y + + + + + + Extracts the number of fingers from a touchpad event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + return location for the number of fingers + + + + + + Extracts the touchpad gesture phase from a touchpad event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + Return location for the gesture phase + + + + + + Extracts the scale from a touchpad event. + + + %TRUE on success, otherwise %FALSE + + + + + a #GdkEvent + + + + Return location for scale + + + + + + 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 + + + + + + Returns whether the event was sent explicitly. + + + %TRUE if the event was sent explicitly + + + + + 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 display that an event is associated with. + + + + + + + a #GdkEvent + + + + a #GdkDisplay + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A set of bit-flags to indicate which events a surface 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]. + +If %GDK_TOUCH_MASK is enabled, the surface 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 + + + 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 surface enter events + + + receive surface leave events + + + receive focus change events + + + receive events about surface configuration change + + + receive property change events + + + receive proximity in events + + + receive proximity out events + + + receive events about surface configuration changes of child surfaces + + + receive scroll events + + + receive touch events + + + receive smooth scrolling events + + + receive touchpad gesture events + + + receive tablet pad events + + + the combination of all the above event masks. + + + + + + + + + + + + + + + + + + + + + + GdkEventSequence is an opaque type representing a sequence +of related touch events. + + + + + + + + + + + + + + + + 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. + + a special code to indicate a null 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 surface has been destroyed. + + + 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. + + + the size, position or stacking order of the surface has changed. + Note that GTK+ discards these events for %GDK_SURFACE_CHILD surfaces. + + + 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. This event type + was added in 2.8. + + + 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 + + + + + + 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 surface 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 draw context. + +#GdkGLContexts are created for a #GdkSurface using +gdk_surface_create_gl_context(), and the context will match the +the characteristics of the surface. + +A #GdkGLContext is not tied to any particular normal framebuffer. +For instance, it cannot draw to the #GdkSurface 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 +#GdkSurface, 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_surface_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 + + + + + + Retrieves the #GdkSurface used by the @context. + + + a #GdkSurface 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 + + + + + + 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 #GdkGLContext that this context is sharing data with, or %NULL + + + + + 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 + + + + + + + + + + + + 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 gdk_gl_texture_release(). + + + 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 that +was created with gdk_gl_texture_new(). + +The texture contents are still available via the +gdk_texture_download() function, after this function +has been called. + + + + + + + a #GdkTexture wrapping a GL texture + + + + + + + + + + The #GdkGeometry struct gives the window manager information about +a surface’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 #GdkSurface it creates. + +gdk_surface_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 surface 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 surface. 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 surface (or -1 to use requisition, with + #GtkWindow only) + + + + minimum height of surface (or -1 to use requisition, with + #GtkWindow only) + + + + maximum width of surface (or -1 to use requisition, with + #GtkWindow only) + + + + maximum height of surface (or -1 to use requisition, with + #GtkWindow only) + + + + allowed surface widths are @base_width + @width_inc * N where N + is any integer (-1 allowed with #GtkWindow) + + + + allowed surface 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 + + + + surface 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 surface. + + + Other devices’ events are blocked for the whole application. + + + + Returned by gdk_device_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 surface or the @confine_to surface are not + viewable. + + + the resource is frozen by an active grab of another client. + + + the grab failed for some other reason + + + + Defines the reference point of a surface 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 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 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 surface. The manner in which this surface + is chosen is undefined, but it will typically be the same + way in which the focus surface 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. + + 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. +The direction of a layout is the direction of the majority of its +symbols. See pango_unichar_direction(). + + + %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL + if it can determine the direction. %PANGO_DIRECTION_NEUTRAL + otherwise. + + + + + a #GdkKeymap + + + + + + Retrieves the #GdkDisplay associated to the @keymap. + + + a #GdkDisplay + + + + + 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. See gdk_keymap_get_direction(). + + + + + + 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. + + + + + + + + + #GdkMemoryFormat describes a format that bytes 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 (see +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 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. + + + The number of formats. This value will change as + more formats get added, so do not rely on its concrete integer. + + + + + + + Creates a new texture for a blob of image data. +The #GBytes must contain @stride x @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 + + + + + + + + + + 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. + +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 + + + the Hyper modifier + + + the Meta modifier + + + 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_surface(). + + + 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 of the monitor's manufacturer, if available. + + + 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 surface +where it is better to use gdk_surface_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 + + + + + + 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 ::invalidate signal gets emitted when the output represented +by @monitor gets disconnected. + + + + + + + + + + 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. + + + + A special value, indicating that the background +for a surface should be inherited from the parent surface. + + + + + This is the priority that the idle handler processing surface updates +is given in the +[GLib Main Loop][glib-The-Main-Event-Loop]. + + + + + #GdkPaintable is a simple interface used by GDK and GDK to represent +objects that 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 +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 #GdkSnapshot 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 snpashot. Once that happens, it will call +gdk_paintable_invalidate_contents() which will emit the +#GdkPaintable::invalidate-contents signal. +If a paintable is known to never change its contents, it will set the +%GDK_PAINTABLE_STATIC_CONTENT flag. If a consumer cannot deal with changing +contents, it may call gdk_paintable_get_static_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 gdk_paintable_invalidate_size() which will emit the +#GdkPaintable::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: +gdk_paintable_invalidate_contents(), +gdk_paintable_invalidate_size(), +gdk_paintable_new_empty(). + + + Returns a paintable that has the given intrinsic size and draws nothing. +This is often useful for implementing the GdkPaintableClass:get_current_image() +virtual function when the paintable is in an incomplete state (like a +#GtkMediaStream 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 #GdkPaintableFlags 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 ration 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 +this paintable. + +This is a purely informational value and does not in any way limit the values +that may be passed to gdk_paintable_snapshot(). + +Usually when a @paintable returns non-0 values from +gdk_paintable_get_intrinsic_width() and 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.0. +Negative values are never returned. + + + the intrinsic aspect ratio of @paintable or 0.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 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 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 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 + + + + + + Applies the sizing algorithm outlined in +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 #GdkPaintableFlags 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 ration 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 +this paintable. + +This is a purely informational value and does not in any way limit the values +that may be passed to gdk_paintable_snapshot(). + +Usually when a @paintable returns non-0 values from +gdk_paintable_get_intrinsic_width() and 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.0. +Negative values are never returned. + + + the intrinsic aspect ratio of @paintable or 0.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 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 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 to GdkPaintable::snapshot produce the same output. + +This function will emit the GdkPaintable::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 width, height and intrinsic height. + +This function will emit the GdkPaintable::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 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 gdk_paintable_get_intrinsic_width(), +gdk_paintable_get_intrinsic_height() or 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 this object. Implementations use these for optimizations +such as caching. + + The size is immutable. + The GdkPaintable::invalidate-size signal will never be + emitted. + + + The content is immutable. + The GdkPaintable::invalidate-content signal will never be + emitted. + + + + The list of functions that can be implemented for the #GdkPaintable interface. +Note that apart from the first function, no function is mandatory to implement, +though it is a good idea to implement GdkPaintable:get_current_image() for +non-static paintables and GdkPaintable:get_flags() if the image is not dynamic +as the default implementation returns no flags and that will make the +implementation likely quite slow. + + + + + + + + + + + + + a #GdkPaintable + + + + a #GdkSnapshot to snapshot to + + + + width to snapshot in + + + + height to snapshot in + + + + + + + + + + An immutable paintable for the current + contents of @paintable. + + + + + a #GdkPaintable + + + + + + + + + + The #GdkPaintableFlags for this paintable. + + + + + a #GdkPaintable + + + + + + + + + + the intrinsic width of @paintable or 0 if none. + + + + + a #GdkPaintable + + + + + + + + + + the intrinsic height of @paintable or 0 if none. + + + + + a #GdkPaintable + + + + + + + + + + the intrinsic aspect ratio of @paintable or 0.0 if none. + + + + + a #GdkPaintable + + + + + + + + Defines the x and y coordinates of a point. + + + the x coordinate of the point + + + + the y coordinate of the point + + + + + 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 + + + + + + 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, 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. + + + 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, 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 + + + + + + + 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_event_get_scroll_deltas() + + + + 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 all master pointers with the given capabilities driven by this @seat. +On most backends this function will return a list with a single element (meaning +that all input devices drive the same onscreen cursor). + +In other backends where there can possibly be multiple foci (eg. wayland), +this function will return all master #GdkDevices that represent these. + + + A list +of master pointing devices + + + + + + + The #GdkSeat + + + + Queried capabilities + + + + + + 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 surface 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 #GdkSurface 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 surface 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 #GdkSurface which will own the grab + + + + capabilities that will be grabbed + + + + if %FALSE then all device events are reported with respect to + @surface 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 @surface 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 + @surface and its descendants, and the cursor for @surface is used + elsewhere. + + + + the event that is triggering the grab, or %NULL if none + is available. + + + + function to + prepare the surface to be grabbed, it can be %NULL if @surface 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 seat has drawing tablet pad(s) attached + + + The union of all pointing capabilities + + + The union of all capabilities + + + + Type of the callback used to set up @surface so it can be +grabbed. A typical action would be ensuring the surface is +visible, although there's room for other initialization +actions. + + + + + + + the #GdkSeat being grabbed + + + + the #GdkSurface being grabbed + + + + user data passed in gdk_seat_grab() + + + + + + + + + + + + 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 + + + + A #GdkSurface 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 +surface, the thing a user might think of as a “window” with a titlebar +and so on; a #GtkWindow may contain many sub-GdkSurfaces. + + + Creates a new client-side child surface. + + + the new #GdkSurface + + + + + the parent surface + + + + placement of the surface inside @parent + + + + + + Creates a new toplevel popup surface. The surface will bypass surface +management. + + + the new #GdkSurface + + + + + the display to create the surface on + + + + position of the surface on screen + + + + + + Creates a new toplevel temporary surface. The surface will be +situated off-screen and not handle output. + +You most likely do not want to use this function. + + + the new #GdkSurface + + + + + the display to create the surface on + + + + + + Creates a new toplevel surface. The surface will be managed by the surface +manager. + + + the new #GdkSurface + + + + + the display to create the surface on + + + + width of new surface + + + + height of new surface + + + + + + 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 surface + + + + desired height of the surface + + + + location to store resulting width + + + + location to store resulting height + + + + + + Emits a short beep associated to @surface in the appropriate +display, if supported. Otherwise, emits a short beep on +the display just as gdk_display_beep(). + + + + + + + a toplevel #GdkSurface + + + + + + Begins a surface move operation (for a toplevel surface). + +This function assumes that the drag is controlled by the +client pointer device, use gdk_surface_begin_move_drag_for_device() +to begin a drag with a different device. + + + + + + + a toplevel #GdkSurface + + + + 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 + + + + + + Begins a surface move operation (for a toplevel surface). + + + + + + + a toplevel #GdkSurface + + + + 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 + + + + + + Begins a surface resize operation (for a toplevel surface). + +This function assumes that the drag is controlled by the +client pointer device, use gdk_surface_begin_resize_drag_for_device() +to begin a drag with a different device. + + + + + + + a toplevel #GdkSurface + + + + the edge or corner from which the drag is started + + + + 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 gdk_event_get_time()) + + + + + + Begins a surface resize operation (for a toplevel surface). +You might use this function to implement a “window resize grip,” + + + + + + + a toplevel #GdkSurface + + + + 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 gdk_event_get_time()) + + + + + + Transforms surface coordinates from a parent surface to a child +surface. + +Calling this function is equivalent to subtracting the return +values of gdk_surface_get_position() from the parent coordinates. + +See also: gdk_surface_coords_to_parent() + + + + + + + a child surface + + + + 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 surface coordinates from a child surface to its parent +surface. Calling this function is equivalent to adding the return +values of gdk_surface_get_position() to the child coordinates. + +See also: gdk_surface_coords_from_parent() + + + + + + + a child surface + + + + 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 #GdkCairoContext for rendering on @surface. + + + the newly created #GdkCairoContext + + + + + a #GdkSurface + + + + + + Creates a new #GdkGLContext matching the +framebuffer format to the visual of 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 gdk_gl_context_make_current() or gdk_gl_context_realize(). + + + the newly created #GdkGLContext, or +%NULL on error + + + + + a #GdkSurface + + + + + + Create a new 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.) + + + 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. + + + + + surface to make new surface similar to + + + + the content for the new surface + + + + width of the new surface + + + + height of the new surface + + + + + + Creates a new #GdkVulkanContext for rendering on @surface. + +If the creation of the #GdkVulkanContext failed, @error will be set. + + + the newly created #GdkVulkanContext, or +%NULL on error + + + + + a #GdkSurface + + + + + + Attempt to deiconify (unminimize) @surface. On X11 the window manager may +choose to ignore the request to deiconify. When using GTK, +use gtk_window_deiconify() instead of the #GdkSurface variant. Or better yet, +you probably want to use gtk_window_present_with_time(), which raises the surface, focuses it, +unminimizes it, and puts it on the current desktop. + + + + + + + a toplevel #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 + + + + + + Sets keyboard focus to @surface. In most cases, gtk_window_present_with_time() +should be used on a #GtkWindow, rather than calling this function. + + + + + + + a #GdkSurface + + + + timestamp of the event triggering the surface focus + + + + + + Temporarily freezes a surface such that it won’t receive expose +events. The surface will begin receiving expose events again when +gdk_surface_thaw_updates() is called. If gdk_surface_freeze_updates() +has been called more than once, gdk_surface_thaw_updates() must be called +an equal number of times to begin processing exposes. + + + + + + + a #GdkSurface + + + + + + Moves the surface into fullscreen mode. This means the +surface covers the entire screen and is above any panels +or task bars. + +If the surface was already fullscreen, then this function does nothing. + +On X11, asks the window manager to put @surface 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 #GdkSurface + + + + + + Moves the surface into fullscreen mode on the given monitor. This means +the surface covers the entire screen and is above any panels or task bars. + +If the surface was already fullscreen, then this function does nothing. + + + + + + + a toplevel #GdkSurface + + + + Which monitor to display fullscreen on. + + + + + + Determines whether or not the desktop environment shuld be hinted that +the surface does not want to receive input focus. + + + whether or not the surface should receive input focus. + + + + + a toplevel #GdkSurface. + + + + + + Gets the list of children of @surface 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 surfaces an application created itself. + +The returned list must be freed, but the elements in the +list need not be. + + + + list of child surfaces inside @surface + + + + + + + a #GdkSurface + + + + + + Retrieves a #GdkCursor pointer for the cursor currently set on the +specified #GdkSurface, or %NULL. 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. + + + a #GdkCursor, or %NULL. The + returned object is owned by the #GdkSurface and should not be + unreferenced directly. Use gdk_surface_set_cursor() to unset the + cursor of the surface + + + + + a #GdkSurface + + + + + + Returns the decorations set on the GdkSurface with +gdk_surface_set_decorations(). + + + %TRUE if the surface has decorations set, %FALSE otherwise. + + + + + The toplevel #GdkSurface to get the decorations from + + + + The surface decorations will be written here + + + + + + Retrieves a #GdkCursor pointer for the @device currently set on the +specified #GdkSurface, or %NULL. 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. + + + a #GdkCursor, or %NULL. The + returned object is owned by the #GdkSurface and should not be + unreferenced directly. Use gdk_surface_set_cursor() to unset the + cursor of the surface + + + + + a #GdkSurface. + + + + a master, pointer #GdkDevice. + + + + + + Obtains the current device position in doubles and modifier state. +The position is given in coordinates relative to the upper left +corner of @surface. + + + The surface underneath @device +(as with gdk_device_get_surface_at_position()), or %NULL if the +surface is not known to GDK. + + + + + a #GdkSurface. + + + + 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 #GdkSurface. + + + the #GdkDisplay associated with @surface + + + + + a #GdkSurface + + + + + + Determines whether or not the desktop environment should be hinted that the +surface does not want to receive input focus when it is mapped. + + + whether or not the surface wants to receive input focus when +it is mapped. + + + + + a toplevel #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 + + + + + + Obtains the bounding box of the surface, including window manager +titlebar/borders if any. The frame position is given in root window +coordinates. To get the position of the surface itself (rather than +the frame) in root window coordinates, use gdk_surface_get_origin(). + + + + + + + a toplevel #GdkSurface + + + + rectangle to fill with bounding box of the surface frame + + + + + + Obtains the #GdkFullscreenMode of the @surface. + + + The #GdkFullscreenMode applied to the surface when fullscreen. + + + + + a toplevel #GdkSurface + + + + + + 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 surface +of @surface, which for toplevels usually means relative to the +surface 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 @surface; this may be out-of-sync +with the position of @surface delivered in the most-recently-processed +#GdkEventConfigure. gdk_surface_get_position() in contrast gets the +position from the most recent configure event. + +Note: If @surface is not a toplevel, it is much better +to call gdk_surface_get_position(), gdk_surface_get_width() and +gdk_surface_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_surface_get_geometry() is restricted to +the 16-bit coordinates of X11. + + + + + + + a #GdkSurface + + + + return location for X coordinate of surface (relative to its parent) + + + + return location for Y coordinate of surface (relative to its parent) + + + + return location for width of surface + + + + return location for height of surface + + + + + + Returns the height of the given @surface. + +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 @surface + + + + + a #GdkSurface + + + + + + Determines whether or not the window manager is hinted that @surface +has modal behaviour. + + + whether or not the surface has the modal hint set. + + + + + A toplevel #GdkSurface. + + + + + + Obtains the position of a surface in root window coordinates. +(Compare with gdk_surface_get_position() and +gdk_surface_get_geometry() which return the position of a surface +relative to its parent surface.) + + + not meaningful, ignore + + + + + a #GdkSurface + + + + return location for X coordinate + + + + return location for Y coordinate + + + + + + Obtains the parent of @surface, as known to GDK. Does not query the +X server; thus this returns the parent as passed to gdk_surface_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. + + + parent of @surface + + + + + a #GdkSurface + + + + + + Returns whether input to the surface is passed through to the surface +below. + +See gdk_surface_set_pass_through() for details + + + + + + + a #GdkSurface + + + + + + Obtains the position of the surface as reported in the +most-recently-processed #GdkEventConfigure. Contrast with +gdk_surface_get_geometry() which queries the X server for the +current surface position, regardless of which events have been +received or processed. + +The position coordinates are relative to the surface’s parent surface. + + + + + + + a #GdkSurface + + + + X coordinate of surface + + + + Y coordinate of surface + + + + + + Obtains the position of a surface position in root +window coordinates. This is similar to +gdk_surface_get_origin() but allows you to pass +in any position in the surface, not just the origin. + + + + + + + a #GdkSurface + + + + X coordinate in surface + + + + Y coordinate in surface + + + + return location for X coordinate + + + + return location for Y coordinate + + + + + + Obtains the top-left corner of the window manager frame in root +surface coordinates. + + + + + + + a toplevel #GdkSurface + + + + return location for X position of surface frame + + + + return location for Y position of surface frame + + + + + + Returns the internal scale factor that maps from surface 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 surface may change during runtime, if this happens +a configure event will be sent to the toplevel surface. + + + the scale factor + + + + + surface to get scale factor for + + + + + + Gets the bitwise OR of the currently active surface state flags, +from the #GdkSurfaceState enumeration. + + + surface state bitfield + + + + + a #GdkSurface + + + + + + Returns %TRUE if the surface is aware of the existence of multiple +devices. + + + %TRUE if the surface handles multidevice features. + + + + + a #GdkSurface. + + + + + + Gets the type of the surface. See #GdkSurfaceType. + + + type of surface + + + + + a #GdkSurface + + + + + + Gets the toplevel surface that’s an ancestor of @surface. + +Any surface type but %GDK_SURFACE_CHILD is considered a +toplevel surface, as is a %GDK_SURFACE_CHILD surface that +has a root surface as parent. + + + the toplevel surface containing @surface + + + + + a #GdkSurface + + + + + + This function returns the type hint set for a surface. + + + The type hint set for @surface + + + + + A toplevel #GdkSurface + + + + + + Returns the width of the given @surface. + +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 @surface + + + + + a #GdkSurface + + + + + + Checks whether the surface has a native surface or not. + + + %TRUE if the @surface has a native surface, %FALSE otherwise. + + + + + a #GdkSurface + + + + + + 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(). + + + + + + + a #GdkSurface + + + + + + Asks to iconify (minimize) @surface. 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 @surface is a toplevel surface. + + + + + + + a toplevel #GdkSurface + + + + + + Like gdk_surface_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 surface below @surface. + +An input shape 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 shape controls where the surface 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 #GdkSurface + + + + region of surface to be non-transparent + + + + X position of @shape_region in @surface coordinates + + + + Y position of @shape_region in @surface coordinates + + + + + + Check to see if a surface is destroyed.. + + + %TRUE if the surface is destroyed + + + + + a #GdkSurface + + + + + + Determines whether or not the surface is an input only surface. + + + %TRUE if @surface is input only + + + + + a toplevel #GdkSurface + + + + + + Check if the surface and all ancestors of the surface are +mapped. (This is not necessarily "viewable" in the X sense, since +we only check as far as we have GDK surface parents, not to the root +surface.) + + + %TRUE if the surface is viewable + + + + + a #GdkSurface + + + + + + Checks whether the surface has been mapped (with gdk_surface_show() or +gdk_surface_show_unraised()). + + + %TRUE if the surface is mapped + + + + + a #GdkSurface + + + + + + Lowers @surface to the bottom of the Z-order (stacking order), so that +other surfaces with the same parent surface appear above @surface. +This is true whether or not the other surfaces are visible. + +If @surface is a toplevel, the window manager may choose to deny the +request to move the surface in the Z-order, gdk_surface_lower() only +requests the restack, does not guarantee it. + +Note that gdk_surface_show() raises the surface again, so don’t call this +function before gdk_surface_show(). (Try gdk_surface_show_unraised().) + + + + + + + a #GdkSurface + + + + + + Maximizes the surface. If the surface was already maximized, then +this function does nothing. + +On X11, asks the window manager to maximize @surface, 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 surface. + + + + + + + a toplevel #GdkSurface + + + + + + Merges the input shape masks for any child surfaces into the +input shape mask for @surface. i.e. the union of all input masks +for @surface and its children will become the new input mask +for @surface. See gdk_surface_input_shape_combine_region(). + +This function is distinct from gdk_surface_set_child_input_shapes() +because it includes @surface’s input shape mask in the set of +shapes to be merged. + + + + + + + a #GdkSurface + + + + + + Repositions a surface relative to its parent surface. +For toplevel surfaces, 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 surfaces, +the move will reliably succeed. + +If you’re also planning to resize the surface, use gdk_surface_move_resize() +to both move and resize simultaneously, for a nicer visual effect. + + + + + + + a #GdkSurface + + + + X coordinate relative to surface’s parent + + + + Y coordinate relative to surface’s parent + + + + + + Equivalent to calling gdk_surface_move() and gdk_surface_resize(), +except that both operations are performed at once, avoiding strange +visual effects. (i.e. the user may be able to see the surface first +move, then resize, if you don’t use gdk_surface_move_resize().) + + + + + + + a #GdkSurface + + + + new X position relative to surface’s parent + + + + new Y position relative to surface’s parent + + + + new width + + + + new height + + + + + + Moves @surface to @rect, aligning their anchor points. + +@rect is relative to the top-left corner of the surface that @surface is +transient for. @rect_anchor and @surface_anchor determine anchor points on +@rect and @surface 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 @surface. + +@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. + +Connect to the #GdkSurface::moved-to-rect signal to find out how it was +actually positioned. + + + + + + + the #GdkSurface to move + + + + the destination #GdkRectangle to align @surface with + + + + the point on @rect to align with @surface's anchor point + + + + the point on @surface to align with @rect's anchor point + + + + positioning hints to use when limited on space + + + + horizontal offset to shift @surface, i.e. @rect's anchor + point + + + + vertical offset to shift @surface, i.e. @rect's anchor point + + + + + + Like gdk_surface_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 surfaces in @surface + + + + + + + a #GdkSurface + + + + + + Forces an expose event for @surface to be scheduled. + +If the invalid area of @surface is empty, an expose event will +still be emitted. Its invalid region will be empty. + +This function is useful for implementations that track invalid +regions on their own. + + + + + + + a #GdkSurface + + + + + + Raises @surface to the top of the Z-order (stacking order), so that +other surfaces with the same parent surface appear below @surface. +This is true whether or not the surfaces are visible. + +If @surface is a toplevel, the window manager may choose to deny the +request to move the surface in the Z-order, gdk_surface_raise() only +requests the restack, does not guarantee it. + + + + + + + a #GdkSurface + + + + + + Registers a surface as a potential drop destination. + + + + + + + a #GdkSurface. + + + + + + Resizes @surface; for toplevel surfaces, asks the window manager to resize +the surface. The window manager may not allow the resize. When using GTK, +use gtk_window_resize() instead of this low-level GDK function. + +Surfaces may not be resized below 1x1. + +If you’re also planning to move the surface, use gdk_surface_move_resize() +to both move and resize simultaneously, for a nicer visual effect. + + + + + + + a #GdkSurface + + + + new width of the surface + + + + new height of the surface + + + + + + Changes the position of @surface 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 surface. + +If @surface is a toplevel, the window manager may choose to deny the +request to move the surface in the Z-order, gdk_surface_restack() only +requests the restack, does not guarantee it. + + + + + + + a #GdkSurface + + + + a #GdkSurface that is a sibling of @surface, or %NULL + + + + a boolean + + + + + + Setting @accept_focus to %FALSE hints the desktop environment that the +surface 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 #GdkSurface + + + + %TRUE if the surface should receive input focus + + + + + + Sets the input shape mask of @surface to the union of input shape masks +for all children of @surface, ignoring the input shape mask of @surface +itself. Contrast with gdk_surface_merge_child_input_shapes() which includes +the input shape mask of @surface in the masks to be merged. + + + + + + + a #GdkSurface + + + + + + Sets the default mouse pointer for a #GdkSurface. + +Note that @cursor must be for the same display as @surface. + +Use gdk_cursor_new_from_name() or gdk_cursor_new_from_texture() to +create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. +Passing %NULL for the @cursor argument to gdk_surface_set_cursor() means +that @surface will use the cursor of its parent surface. Most surfaces +should use this default. + + + + + + + a #GdkSurface + + + + a cursor + + + + + + “Decorations” are the features the window manager adds to a toplevel #GdkSurface. +This function sets the traditional Motif window manager hints that tell the +window manager which decorations you would like your surface 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 #GdkSurface + + + + decoration hint mask + + + + + + Sets a specific #GdkCursor for a given device when it gets inside @surface. +Use gdk_cursor_new_fromm_name() or gdk_cursor_new_from_texture() to create +the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR. Passing +%NULL for the @cursor argument to gdk_surface_set_cursor() means that +@surface will use the cursor of its parent surface. Most surfaces should +use this default. + + + + + + + a #GdkSurface + + + + a master, pointer #GdkDevice + + + + a #GdkCursor + + + + + + Setting @focus_on_map to %FALSE hints the desktop environment that the +surface doesn’t want to receive input focus when it is mapped. +focus_on_map should be turned off for surfaces 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 #GdkSurface + + + + %TRUE if the surface should receive input focus when mapped + + + + + + Specifies whether the @surface 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 @surface will +span over all monitors of the display. + +On X11, searches through the list of monitors display the ones +which delimit the 4 edges of the entire display and will ask the window +manager to span the @surface 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 +surface to span over the multiple monitors when #GDK_FULLSCREEN_ON_ALL_MONITORS +is specified. + + + + + + + a toplevel #GdkSurface + + + + 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 #GdkSurface + + + + bitmask of operations to allow on @surface + + + + + + Sets the geometry hints for @surface. 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 surfaceing system about +acceptable sizes for a toplevel surface. 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 surface to the provided values and +constrain programatic resizing via gdk_surface_resize() or +gdk_surface_move_resize(). + +Note that on X11, this effect has no effect on surfaces +of type %GDK_SURFACE_TEMP since these surfaces 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_surface_constrain_size() yourself to determine +appropriate sizes. + + + + + + + a toplevel #GdkSurface + + + + geometry hints + + + + bitmask indicating fields of @geometry to pay attention to + + + + + + Sets a list of icons for the surface. One of these will be used +to represent the surface 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 surface icons. + + + + + + + The #GdkSurface toplevel surface to set the icon of. + + + + + A list of image surfaces, of different sizes. + + + + + + + + Surfaces 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_surface_set_title() +will not update the icon title. + +Using %NULL for @name unsets the icon title; further calls to +gdk_surface_set_title() will again update the icon title as well. + +Note that some platforms don't support surface icons. + + + + + + + a toplevel #GdkSurface + + + + name of surface while iconified (minimized) + + + + + + Set if @surface must be kept above other surfaces. If the +surface was already above, then this function does nothing. + +On X11, asks the window manager to keep @surface 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 surface 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 #GdkSurface + + + + whether to keep @surface above other surfaces + + + + + + Set if @surface must be kept below other surfaces. If the +surface was already below, then this function does nothing. + +On X11, asks the window manager to keep @surface 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 surface 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 #GdkSurface + + + + whether to keep @surface below other surfaces + + + + + + 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 gdk_surface_set_transient_for() + + + + + + + A toplevel #GdkSurface + + + + %TRUE if the surface is modal, %FALSE otherwise. + + + + + + Set @surface 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 surfaces 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-surface opacity value that the compositor would apply. Instead, use +`gdk_surface_set_opaque_region (surface, NULL)` to tell the compositor +that the entire surface is (potentially) non-opaque, and draw your content +with alpha, or use gtk_widget_set_opacity() to set an overall opacity +for your widgets. + +Support for non-toplevel surfaces was added in 3.8. + + + + + + + a top-level or non-native #GdkSurface + + + + opacity + + + + + + 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 #GtkWidget::style-updated handler. + + + + + + + a top-level or non-native #GdkSurface + + + + a region, or %NULL + + + + + + Sets whether input to the surface is passed through to the surface +below. + +The default value of this is %FALSE, which means that pointer +events that happen inside the surface are send first to the surface, +but if the event is not selected by the event mask then the event +is sent to the parent surface, and so on up the hierarchy. + +If @pass_through is %TRUE then such pointer events happen as if the +surface wasn't there at all, and thus will be sent first to any +surfaces below @surface. This is useful if the surface is used in a +transparent fashion. In the terminology of the web this would be called +"pointer-events: none". + +Note that a surface with @pass_through %TRUE can still have a subsurface +without pass through, so you can get events on a subset of a surface. 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 surface. + + + + + + + a #GdkSurface + + + + a boolean + + + + + + 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 surfaces. + + + + + + + a #GdkSurface + + + + The left extent + + + + The right extent + + + + The top extent + + + + The bottom extent + + + + + + When using GTK, typically you should use gtk_window_set_startup_id() +instead of this low-level function. + + + + + + + a toplevel #GdkSurface + + + + a string with startup-notification identifier + + + + + + This function will enable multidevice features in @surface. + +Multidevice aware surfaces will need to handle properly multiple, +per device enter/leave events, device grabs and grab ownerships. + + + + + + + a #GdkSurface. + + + + %TRUE to enable multidevice support in @surface. + + + + + + Sets the title of a toplevel surface, to be displayed in the titlebar. +If you haven’t explicitly set the icon name for the surface +(using gdk_surface_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 and GTK). @title may not be %NULL. + + + + + + + a toplevel #GdkSurface + + + + title of @surface + + + + + + 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() if you’re using #GtkWindow or +#GtkDialog. + + + + + + + a toplevel #GdkSurface + + + + another toplevel #GdkSurface + + + + + + The application can use this call to provide a hint to the surface +manager about the functionality of a surface. The window manager +can use this information when determining the decoration and behaviour +of the surface. + +The hint must be set before the surface is mapped. + + + + + + + A toplevel #GdkSurface + + + + A hint of the function this surface will have + + + + + + Like gdk_surface_show_unraised(), but also raises the surface to the +top of the surface stack (moves the surface to the front of the +Z-order). + +This function maps a surface so it’s visible onscreen. Its opposite +is gdk_surface_hide(). + +When implementing a #GtkWidget, you should call this function on the widget's +#GdkSurface as part of the “map” method. + + + + + + + a #GdkSurface + + + + + + Shows a #GdkSurface onscreen, but does not modify its stacking +order. In contrast, gdk_surface_show() will raise the surface +to the top of the surface 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 surface). + + + + + + + a #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 #GdkSurface + + + + a #GdkEvent to show the menu for + + + + + + “Pins” a surface 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 surface. For window managers that don’t support this operation, +there’s nothing you can do to force it to happen. + + + + + + + a toplevel #GdkSurface + + + + + + Thaws a surface frozen with gdk_surface_freeze_updates(). + + + + + + + a #GdkSurface + + + + + + Moves the surface out of fullscreen mode. If the surface was not +fullscreen, does nothing. + +On X11, asks the window manager to move @surface 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 #GdkSurface + + + + + + Unmaximizes the surface. If the surface wasn’t maximized, then this +function does nothing. + +On X11, asks the window manager to unmaximize @surface, 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 surface. + + + + + + + a toplevel #GdkSurface + + + + + + Reverse operation for gdk_surface_stick(); see gdk_surface_stick(), +and gtk_window_unstick(). + + + + + + + a toplevel #GdkSurface + + + + + + The mouse pointer for a #GdkSurface. See gdk_surface_set_cursor() and +gdk_surface_get_cursor() for details. + + + + The #GdkDisplay connection of the surface. See gdk_surface_get_display() +for details. + + + + + + + + + + + + + Emitted when GDK receives an input event for @surface. + + %TRUE to indicate that the event has been handled + + + + + an input event + + + + + + Emitted when the position of @surface is finalized after being moved to a +destination rectangle. + +@surface 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 @surface 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 @surface on-screen. + + + + + + the position of @surface after any possible + flipping or %NULL if the backend can't obtain it + + + + the final position of @surface or %NULL if the + backend can't obtain it + + + + %TRUE if the anchors were flipped horizontally + + + + %TRUE if the anchors were flipped vertically + + + + + + 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 + + + + + + Emitted when the size of @surface is changed. + + + + + + the new width + + + + the new height + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + 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 surface + + + 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 + + + surface gravity field is set + + + indicates that the surface’s position was explicitly set + by the user + + + indicates that the surface’s size was explicitly set by + the user + + + + Specifies the state of a toplevel surface. + +On platforms that support information about individual edges, the %GDK_SURFACE_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 not shown + + + 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 + + + + Describes the kind of surface. + + toplevel window (used to implement #GtkWindow) + + + child surface (used to implement e.g. #GtkEntry) + + + override redirect temporary surface (used to implement #GtkMenu) + + + + 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. + + + + A GdkTexture represents image data that can be displayed on screen. + +There are various ways to create GdkTexture objects from a #GdkPixbuf +or a cairo surface, or other pixel data. + +An important aspect of GdkTextures is that they are immutable - once +the image data has been wrapped in a GdkTexture, it may be uploaded +to the GPU or used in other ways that make it impractical to allow +modification. + + + + Creates a new texture object representing the GdkPixbuf. + + + a new #GdkTexture + + + + + a #GdkPixbuf + + + + + + Creates a new texture by loading an image from a file. The file format is +detected automatically. If %NULL is returned, then @error will be set. + + + A newly-created #GdkTexture or %NULL if an error occured. + + + + + #GFile to load + + + + + + Creates a new texture by loading an image from a resource. +The file format is detected automatically. + +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 +gdk_texture_new_from_file() to load it. + + + A newly-created texture + + + + + 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: +|[<!-- language="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); +]| + + + + + + + a #GdkTexture + + + + pointer to enough memory to be filled with the + downloaded data of @texture + + + + + + rowstride in bytes + + + + + + Returns the height of the @texture. + + + the height of the #GdkTexture + + + + + a #GdkTexture + + + + + + Returns the width of @texture. + + + 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 #GFile or other location, you might want to +look into using the gdk-pixbuf library. + + + %TRUE if saving succeeded, %FALSE on failure. + + + + + a #GdkTexture + + + + the filename to store to + + + + + + The height of the texture. + + + + The width of the texture. + + + + + + + + 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. + + 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. + + + + #GdkVulkanContext is an object representing the platform-specific +Vulkan draw context. + +#GdkVulkanContexts are created for a #GdkSurface using +gdk_surface_create_vulkan_context(), and the context will match the +the characteristics of the surface. + +Support for #GdkVulkanContext is platform-specific, context creation +can fail, returning %NULL context. + + + This signal is 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 + + + + + + + + + These are hints originally defined by the Motif toolkit. +The window manager can use them when determining how to decorate +the surface. The hint must be set before mapping the surface. + + all decorations should be applied. + + + a frame should be drawn around the surface. + + + the frame should have resize handles. + + + a titlebar should be placed above the surface. + + + 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 surface. The +hint must be set before mapping the surface. + + all functions should be offered. + + + the surface should be resizable. + + + the surface should be movable. + + + the surface should be minimizable. + + + the surface should be maximizable. + + + the surface should be closable. + + + + 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 @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. + + + + + + + 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 + + + + + + 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 + + + + + + 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 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 + + + + + + Uploads the contents of a Cairo @surface to a GL texture @target. + + + + + + + a Cairo surface + + + + a GL texture target + + + + the width of the texture @target + + + + the height of the texture @target + + + + a #GdkGLContext, or %NULL to use the currently + bound context + + + + + + Read content from the given input stream and deserialize it, asynchronously. +When the operation is finished, @callback will be called. You can then +call gdk_content_deserialize_finish() to get the result of the operation. + + + + + + + a #GInputStream to read the serialized content from + + + + the mime type to deserialize from + + + + the GType to deserialize from + + + + the io 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 + + + + + + Registers a function to create objects of a given @type from +a serialized representation with the given mime type. + + + + + + + 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 convert objects of the given @type to +a serialized representation with the given mime type. + + + + + + + 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. +When the operation is finished, @callback will be called. You can then +call gdk_content_serialize_finish() to get the result of the operation. + + + + + + + a #GOutputStream to write the serialized content to + + + + the mime type to serialize to + + + + the content to serialize + + + + the io 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 + + + + + + Checks if @action represents a single action or if it +includes multiple flags that can be selected from. + +When @action is 0 - ie no action was given, %TRUE +is returned. + + + %TRUE if exactly one action was given + + + + + a #GdkDragAction + + + + + + 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 + + + + + + Gets whether event debugging output is enabled. + + + %TRUE if event debugging output is enabled. + + + + + + + + + + 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, 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. + + + + + + Returns a paintable that has the given intrinsic size and draws nothing. +This is often useful for implementing the GdkPaintableClass:get_current_image() +virtual function when the paintable is in an incomplete state (like a +#GtkMediaStream 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 an RGB(A) +representation inside 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. + + + 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 + + + + + + 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(), or gtk_init_check() +in order to take effect. + + + + + + + a comma-separated list of backends + + + + + + 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. + + + + + + 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(). + + + + + + + + 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 + + + + + + + + + + + diff --git a/gir-files/GdkPixbuf-2.0.gir b/gir-files/GdkPixbuf-2.0.gir new file mode 100644 index 0000000..4f45c2a --- /dev/null +++ b/gir-files/GdkPixbuf-2.0.gir @@ -0,0 +1,3763 @@ + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This enumeration describes the different interpolation modes that +can be used with the scaling functions. @GDK_INTERP_NEAREST 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 the gdk-pixbuf header as a string. +This is the version being compiled against; contrast with +#gdk_pixbuf_version. + + + + + This is the main structure in the gdk-pixbuf library. It is +used to represent images. It contains information about the +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). + + + + Creates a new #GdkPixbuf structure and allocates a buffer for it. The +buffer has an optimal rowstride. Note that the buffer is not cleared; +you will have to fill it completely yourself. + + + A newly-created #GdkPixbuf with a reference count of 1, or +%NULL if not enough memory could be allocated for the image 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(). + + + A newly-created #GdkPixbuf structure with a reference count of 1. + + + + + 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 gdk_pixbuf_new_from_bytes(). + + + A newly-created #GdkPixbuf structure with a reference count of 1. + + + + + 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 in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. + + + A newly-created pixbuf with a reference count of 1, or %NULL if +any of several error conditions occurred: the file could not be opened, +there was no loader for the file's format, there was not enough memory to +allocate the image buffer, or the image file contained invalid data. + + + + + 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 in the #GDK_PIXBUF_ERROR and #G_FILE_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. 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 with a reference count of 1, or %NULL +if any of several error conditions occurred: the file could not be opened, +there was no loader for the file's format, there was not enough memory to +allocate the image buffer, or the image file contained invalid data. + + + + + 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 in the #GDK_PIXBUF_ERROR and +#G_FILE_ERROR domains. + +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 +gdk_pixbuf_new_from_file_at_scale(). + + + A newly-created pixbuf with a reference count of 1, or +%NULL if any of several error conditions occurred: the file could not +be opened, there was no loader for the file's format, there was not +enough memory to allocate the image buffer, or the image file contained +invalid data. + + + + + 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 + + + + + + Create 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. + +gdk-pixbuf ships with a program called [gdk-pixbuf-csource][gdk-pixbuf-csource], +which allows for conversion of #GdkPixbufs 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: +|[ +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 #GdkPixbuf structure with a reference, + count of 1, or %NULL if an error occurred. + + + + + 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, or %NULL if any of several error +conditions occurred: the file could not be opened, the image format is +not supported, there was not enough memory to allocate the image buffer, +the stream contained invalid data, or the operation was cancelled. + + + + + 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, or %NULL if any of several error +conditions occurred: the file could not be opened, the image format is +not supported, there was not enough memory to allocate the image buffer, +the stream contained invalid data, or the operation was cancelled. + + + + + 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, or %NULL if any of several error +conditions occurred: the file could not be opened, the image format is +not supported, there was not enough memory to allocate the image buffer, +the stream contained invalid data, or the operation was cancelled. + + + + + 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, or %NULL if any of several error +conditions occurred: the file could not be opened, the image format is +not supported, there was not enough memory to allocate the image buffer, +the stream contained invalid data, or the operation was cancelled. + + + + + 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(). + + + a #GdkPixbuf or %NULL on error. Free the returned +object with g_object_unref(). + + + + + 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. + + + A newly-created pixbuf with a reference count of 1. + + + + + Pointer to inline XPM data. + + + + + + + + Calculates the rowstride that an image created with those values would +have. This is useful for front-ends and backends that want to sanity +check image values without needing to create them. + + + 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 or %NULL if the image format wasn't + recognized. The return value is owned by #GdkPixbuf and should + not be freed. + + + + + The name of the file to identify. + + + + Return location for the width of the + image, or %NULL + + + + Return location for the height of the + image, or %NULL + + + + + + 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 or %NULL if the image format wasn't + recognized. The return value is owned by GdkPixbuf and should + not be freed. + + + + + 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 +#GdkPixbufFormats describing the supported image formats. The list should +be freed when it is no longer needed, but the structures themselves are +owned by #GdkPixbuf and should not be freed. + + + + + + + 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 (@r, @g, @b) will be +assigned zero opacity. That is, if you pass (255, 255, 255) for the +substitute color, all white pixels will become fully transparent. + + + A newly-created pixbuf with a reference count of 1. + + + + + A #GdkPixbuf. + + + + Whether to set a color to zero opacity. If this +is %FALSE, then the (@r, @g, @b) arguments will be ignored. + + + + 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, which 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, %NULL if +not enough memory could be allocated for it, or a reference to the +input pixbuf (with an increased reference count). + + + + + A #GdkPixbuf. + + + + + + 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 #GdkPixbuf by scaling @src to @dest_width x +@dest_height and alpha blending the result with a checkboard of colors +@color1 and @color2. + + + the new #GdkPixbuf, or %NULL if not enough memory could be +allocated for it. + + + + + 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 with a reference count of 1, or %NULL if +not enough memory could be allocated. + + + + + 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. + + + + + + Copy the key/value pair options attached to a #GdkPixbuf to another. +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. + + + + + a #GdkPixbuf to copy options from + + + + the #GdkPixbuf to copy options to + + + + + + Clears a pixbuf to the given RGBA value, converting the RGBA value into +the pixbuf's pixel format. The alpha will be ignored if the pixbuf +doesn't have an alpha channel. + + + + + + + a #GdkPixbuf + + + + RGBA pixel to clear to + (0xffffffff is opaque white, 0x00000000 transparent black) + + + + + + Flips a pixbuf horizontally or vertically and returns the +result in a new pixbuf. + + + the new #GdkPixbuf, or %NULL +if not enough memory could be allocated for it. + + + + + 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. This is a nul-terminated +string that should not be freed or %NULL if @key was not found. + + + + + 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 gdk_pixbuf_set_option(). + +See gdk_pixbuf_get_option() for more details. + + + a #GHashTable of key/values + + + + + + + + a #GdkPixbuf + + + + + + Queries a pointer to the pixel data of a pixbuf. + + + A pointer to the pixbuf's pixel data. +Please see the section on [image data][image-data] for information +about how the pixel data is stored in memory. + +This function will cause an implicit copy of the pixbuf data if the +pixbuf was created from read-only data. + + + + + + + A pixbuf. + + + + + + Queries a pointer to the pixel data of a pixbuf. + + + A pointer to the pixbuf's +pixel data. Please see the section on [image data][image-data] +for information about how the pixel data is stored in memory. + +This function will cause an implicit copy of the pixbuf data if the +pixbuf was created from read-only 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; 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 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. + + + + + + Remove 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, a copy of @src is returned, avoiding any rotation. + + + the new #GdkPixbuf, or %NULL +if not enough memory could be allocated for it. + + + + + a #GdkPixbuf + + + + the angle to rotate by + + + + + + Modifies saturation and optionally pixelates @src, placing the result in +@dest. @src and @dest 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. @src and @dest must have the same image format, size, and +rowstride. + + + + + + + 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: + +|[ +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: +|[ +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. + +|[ +gchar *contents; +gchar *contents_encode; +gsize length; +g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL); +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. + + + whether an error was set + + + + + a #GdkPixbuf. + + + + name of file to save. + + + + name of file format. + + + + return location for error, or %NULL + + + + 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 nuls. +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 + + + + + + Saves pixbuf to a new buffer in format @type, which is currently "jpeg", +"tiff", "png", "ico" or "bmp". See gdk_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, %NULL-terminated + + + + + + values for named options + + + + + + + + Saves pixbuf in format @type by feeding the produced data to a +callback. 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 gdk_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 + + + + + + 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 +gdk_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, %NULL-terminated + + + + + + 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. + + + %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 gdk_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, %NULL-terminated + + + + + + 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, %NULL-terminated + + + + + + 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 + + + + + + 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 gdk_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, %NULL-terminated + + + + + + 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 #GdkPixbuf containing a copy of @src scaled to +@dest_width x @dest_height. Leaves @src unaffected. @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 gdk_pixbuf_new_subpixbuf(). + +If @dest_width and @dest_height are equal to the @src width and height, a +copy of @src is returned, avoiding any scaling. + +For more complicated scaling/alpha blending see gdk_pixbuf_scale() +and gdk_pixbuf_composite(). + + + the new #GdkPixbuf, or %NULL if not enough memory could be +allocated for it. + + + + + 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 @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 number of samples per pixel. +Currently, only 3 or 4 samples per pixel are supported. + + + + + + + + + + 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. + + + + + + + + These values can be passed to +gdk_pixbuf_xlib_render_to_drawable_alpha() 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. + + 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 struct representing an animation. + + 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. + + + A newly-created animation with a reference count of 1, or %NULL +if any of several error conditions ocurred: the file could not be opened, +there was no loader for the file's format, there was not enough memory to +allocate the image buffer, or the image file contained invalid data. + + + + + 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. + + + A newly-created animation, or %NULL if any of several error +conditions occurred: the file could not be opened, the image format is +not supported, there was not enough memory to allocate the image buffer, +the stream contained invalid data, or the operation was cancelled. + + + + + 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. + + + A newly-created pixbuf, or %NULL if any of several error +conditions occurred: the file could not be opened, the image format is +not supported, there was not enough memory to allocate the image buffer, +the stream contained invalid data, or the operation was cancelled. + + + + + a #GInputStream to load the pixbuf from + + + + optional #GCancellable object, %NULL to ignore + + + + + + Finishes an asynchronous pixbuf animation creation operation started with +gdk_pixbuf_animation_new_from_stream_async(). + + + a #GdkPixbufAnimation or %NULL on error. Free the returned +object with g_object_unref(). + + + + + 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. + + + + + + + a #GInputStream from which to load the animation + + + + optional #GCancellable object, %NULL to ignore + + + + a #GAsyncReadyCallback to call when the pixbuf is loaded + + + + the data to pass to the callback function + + + + + + Queries the height of the bounding box of a pixbuf animation. + + + 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. It should be +freed after use with g_object_unref(). + +@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." + + + an iterator to move over the animation + + + + + a #GdkPixbufAnimation + + + + time when the animation starts playing + + + + + + 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 thing to display as a static +unanimated image, which might be the first frame, or something more +sophisticated. If an animation hasn't loaded any frames yet, this +function will return %NULL. + + + unanimated image representing the animation + + + + + a #GdkPixbufAnimation + + + + + + Queries the width of the bounding box of a pixbuf animation. + + + Width of the bounding box of the animation. + + + + + An animation. + + + + + + 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. + + + %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. + + + + + + + An opaque struct representing an iterator which points to a +certain position in an animation. + + 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. + + + %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. g_timeout_add() +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. + + + 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. + + + 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. area_updated is emitted +for an area of the frame currently streaming in to the loader. So if +you're on the currently loading frame, you need to redraw the screen for +the updated area. + + + %TRUE if the frame we're on is partially loaded, or the last frame + + + + + a #GdkPixbufAnimationIter + + + + + + + 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 #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. + + + + + + + + + + + Creates a copy of @format + + + the newly allocated copy of a #GdkPixbufFormat. Use + gdk_pixbuf_format_free() to free the resources when done + + + + + a #GdkPixbufFormat + + + + + + Frees the resources allocated when copying a #GdkPixbufFormat +using gdk_pixbuf_format_copy() + + + + + + + a #GdkPixbufFormat + + + + + + 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. + + + a %NULL-terminated array of filename extensions which must be +freed with g_strfreev() when it is no longer needed. + + + + + + + a #GdkPixbufFormat + + + + + + Returns information about the license of the image loader for the format. The +returned string should be a shorthand for a wellknown license, e.g. "LGPL", +"GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. This +string should be freed with g_free() when it's no longer needed. + + + a string describing the license of @format. + + + + + a #GdkPixbufFormat + + + + + + Returns the mime types supported by the format. + + + a %NULL-terminated array of mime types which must be freed with +g_strfreev() when it is no longer needed. + + + + + + + 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 #GdkPixbufFormat + + + + 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, +gdk-pixbuf 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 + + + + + + + The GdkPixbufLoader struct contains only private +fields. + + + 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. 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. 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. 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 does not unref the loader, so if you plan not to +use it anymore, please g_object_unref() it. + + + %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 "area-prepared" +signal has been emitted by the loader. If the loader doesn't have enough +bytes yet (hasn't emitted the "area-prepared" signal) this function will +return %NULL. + + + The #GdkPixbufAnimation that the loader is loading, or %NULL if +not enough data has been read to determine the information. + + + + + A pixbuf loader + + + + + + Obtains the available information about the format of the +currently loading image file. + + + A #GdkPixbufFormat or +%NULL. The return value is owned by GdkPixbuf and should not be +freed. + + + + + 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 +"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 simply calling g_object_ref() should be sufficient to continue +using 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 #GdkPixbuf that the loader is creating, or %NULL if not +enough data has been read to determine how to create the image buffer. + + + + + 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. + + + + + + This will cause a pixbuf loader to parse the next @count bytes of +an image. It will return %TRUE if the data was loaded successfully, +and %FALSE if an error occurred. In the latter case, the loader +will be closed, and will not accept further writes. If %FALSE is +returned, @error will be set to an error from the #GDK_PIXBUF_ERROR +or #G_FILE_ERROR domains. + + + %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. + + + + + + This will cause a pixbuf loader to parse a buffer inside a #GBytes +for an image. It will return %TRUE if the data was loaded successfully, +and %FALSE if an error occurred. In the latter case, the loader +will be closed, and will not accept further writes. If %FALSE is +returned, @error will be set to an error from the #GDK_PIXBUF_ERROR +or #G_FILE_ERROR domains. + +See also: gdk_pixbuf_loader_write() + + + %TRUE if the write was successful, or %FALSE if the loader +cannot parse the buffer. + + + + + A pixbuf loader. + + + + The image data as a #GBytes + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + Specifies the type of the function passed to +gdk_pixbuf_save_to_callback(). It 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 (with @error set) if failed. + + + + + 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. + + + 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. + + + + + + + a #GdkPixbufSimpleAnim + + + + the pixbuf to add + + + + + + Gets whether @animation should loop indefinitely when it reaches the end. + + + %TRUE if the animation loops forever, %FALSE otherwise + + + + + a #GdkPixbufSimpleAnim + + + + + + Sets whether @animation should loop indefinitely when it reaches the end. + + + + + + + a #GdkPixbufSimpleAnim + + + + whether to loop the animation + + + + + + Whether the animation should loop when it reaches the end. + + + + + + + + + + + + + + + diff --git a/gir-files/GdkPixdata-2.0.gir b/gir-files/GdkPixdata-2.0.gir new file mode 100644 index 0000000..ecfdc9d --- /dev/null +++ b/gir-files/GdkPixdata-2.0.gir @@ -0,0 +1,276 @@ + + + + + + + + + Magic number for #GdkPixdata structures. + + + + + The length of a #GdkPixdata structure without the @pixel_data pointer. + + + + + A #GdkPixdata contains pixbuf information in a form suitable for +serialization and streaming. + + + 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 + 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. + +gdk-pixbuf ships with a program called +[gdk-pixbuf-csource][gdk-pixbuf-csource], which offers a command +line interface to this function. + Use #GResource instead. + + + a newly-allocated string containing the C source form + of @pixdata. + + + + + a #GdkPixdata to convert to C source. + + + + used for naming generated data structures or macros. + + + + a #GdkPixdataDumpType determining 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 #GdkPixbuf. + + + + + a #GdkPixdata to convert into a #GdkPixbuf. + + + + whether to copy raw pixel data; run-length encoded + pixel data is always copied. + + + + + + diff --git a/gir-files/GdkX11-3.0.gir b/gir-files/GdkX11-3.0.gir new file mode 100644 index 0000000..63b29dc --- /dev/null +++ b/gir-files/GdkX11-3.0.gir @@ -0,0 +1,1953 @@ + + + + + + + + + + + + + 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 + + + + + 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 + + + + + + diff --git a/gir-files/GdkX11-4.0.gir b/gir-files/GdkX11-4.0.gir new file mode 100644 index 0000000..8b892be --- /dev/null +++ b/gir-files/GdkX11-4.0.gir @@ -0,0 +1,1317 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + Retrieves the #GdkX11Screen of the @display. + + + the #GdkX11Screen + + + + + a #GdkX11Display + + + + + + 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 or + %NULL on error. + + + + + 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. + +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_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 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_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 + + + + + + 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 + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + 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 #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. + + + + a property atom. + + + + + + + + + + + + + + + + + + + + + + + + + + + + Looks up the #GdkSurface that wraps the given native window handle. + + + the #GdkSurface 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 @surface is on. + + + the current workspace of @surface + + + + + a #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 + + + + + + + + + + Disables multidevice support in GDKs X11 backend. This call must happen prior +to gdk_display_open(), gtk_init() 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. + + + + + + + Converts from a #GdkAtom to the X atom for a #GdkDisplay +with the same string value. The special value %NULL +is converted to %None. + + + the X atom corresponding to @atom, or %None + + + + + A #GdkDisplay + + + + A #GdkAtom, or %NULL + + + + + + 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(). + + + + + + 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 modifed 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 + + + + + + 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). + +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. + + + + + + Convert from an X atom for a #GdkDisplay to the corresponding +#GdkAtom. + + + the corresponding #GdkAtom. + + + + + A #GdkDisplay + + + + an X atom + + + + + + diff --git a/gir-files/Gio-2.0.gir b/gir-files/Gio-2.0.gir new file mode 100644 index 0000000..398fd86 --- /dev/null +++ b/gir-files/Gio-2.0.gir @@ -0,0 +1,89008 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GAction represents a single named action. + +The main interface to an action is that it can be activated with +g_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 g_action_change_state(). This call takes a #GVariant. 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 +#GSimpleAction. + +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 g_action_activate() and g_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 #GSimpleActionGroup. + + + 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-utf8 @action_name. +@action_name must not be %NULL. + + + %TRUE if @action_name is valid + + + + + an 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 g_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 '.'. + + + %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 g_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 #GVariant 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 GVariant is floating, it is consumed. + + + + + + + a #GAction + + + + 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 g_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 g_action_get_state_hint(). + +If the @value GVariant is floating, it is consumed. + + + + + + + a #GAction + + + + 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 #GAction + + + + + + Queries the name of @action. + + + the name of the action + + + + + a #GAction + + + + + + Queries the type of the parameter that must be given when activating +@action. + +When activating the action using g_action_activate(), the #GVariant +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 +#GVariant, but %NULL instead. + + + the parameter type + + + + + a #GAction + + + + + + 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 g_action_get_state_type(). + +The return value (if non-%NULL) should be freed with +g_variant_unref() when it is no longer required. + + + the current state of the action + + + + + a #GAction + + + + + + 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 #GVariant array is returned then each item in the array is a +possible value for the state. If a #GVariant 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 +g_variant_unref() when it is no longer required. + + + the state range hint + + + + + a #GAction + + + + + + Queries the type of the state of @action. + +If the action is stateful (e.g. created with +g_simple_action_new_stateful()) then this function returns the +#GVariantType of the state. This is the type of the initial value +given as the state. All calls to g_action_change_state() must give a +#GVariant of this type and g_action_get_state() will return a +#GVariant of the same type. + +If the action is not stateful (e.g. created with g_simple_action_new()) +then this function will return %NULL. In that case, g_action_get_state() +will return %NULL and you must not call g_action_change_state(). + + + the state type, if the action is stateful + + + + + a #GAction + + + + + + 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 GVariant is floating, it is consumed. + + + + + + + a #GAction + + + + 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 g_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 g_action_get_state_hint(). + +If the @value GVariant is floating, it is consumed. + + + + + + + a #GAction + + + + 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 #GAction + + + + + + Queries the name of @action. + + + the name of the action + + + + + a #GAction + + + + + + Queries the type of the parameter that must be given when activating +@action. + +When activating the action using g_action_activate(), the #GVariant +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 +#GVariant, but %NULL instead. + + + the parameter type + + + + + a #GAction + + + + + + 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 g_action_get_state_type(). + +The return value (if non-%NULL) should be freed with +g_variant_unref() when it is no longer required. + + + the current state of the action + + + + + a #GAction + + + + + + 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 #GVariant array is returned then each item in the array is a +possible value for the state. If a #GVariant 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 +g_variant_unref() when it is no longer required. + + + the state range hint + + + + + a #GAction + + + + + + Queries the type of the state of @action. + +If the action is stateful (e.g. created with +g_simple_action_new_stateful()) then this function returns the +#GVariantType of the state. This is the type of the initial value +given as the state. All calls to g_action_change_state() must give a +#GVariant of this type and g_action_get_state() will return a +#GVariant of the same type. + +If the action is not stateful (e.g. created with g_simple_action_new()) +then this function will return %NULL. In that case, g_action_get_state() +will return %NULL and you must not call g_action_change_state(). + + + the state type, if the action is stateful + + + + + a #GAction + + + + + + 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 #GActionGroup. 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 #GVariantType 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 +g_action_map_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 g_action_map_add_action_entries() for an example. + + + the name of the action + + + + + + + + + + + + + + + + + + + + + + + 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][gvariant-text]. 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 #GMenuModel 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 g_action_group_activate_action(). Activating an +action may require a #GVariant parameter. The required type of the +parameter can be inquired with g_action_group_get_action_parameter_type(). +Actions may be disabled, see g_action_group_get_action_enabled(). +Activating a disabled action has no effect. + +Actions may optionally have a state in the form of a #GVariant. The +current state of an action can be inquired with +g_action_group_get_action_state(). Activating a stateful action may +change its state, but it is also possible to set the state by calling +g_action_group_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 g_action_group_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 - g_action_group_get_action_enabled() +but not an equivalent set() call. + +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 g_action_group_list_actions() and +g_action_group_query_action(). The other virtual functions should +not be implemented - their "wrappers" are actually implemented with +calls to g_action_group_query_action(). + + + Emits the #GActionGroup::action-added signal on @action_group. + +This function should only be called by #GActionGroup implementations. + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + + + Emits the #GActionGroup::action-enabled-changed signal on @action_group. + +This function should only be called by #GActionGroup implementations. + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + whether or not the action is now enabled + + + + + + Emits the #GActionGroup::action-removed signal on @action_group. + +This function should only be called by #GActionGroup implementations. + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + + + Emits the #GActionGroup::action-state-changed signal on @action_group. + +This function should only be called by #GActionGroup implementations. + + + + + + + a #GActionGroup + + + + 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 +g_action_group_get_action_parameter_type(). + + + + + + + a #GActionGroup + + + + 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 g_action_group_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 g_action_group_get_action_state_hint(). + +If the @value GVariant is floating, it is consumed. + + + + + + + a #GActionGroup + + + + 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 or not the action is currently enabled + + + + + a #GActionGroup + + + + 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 g_action_group_activate_action(), +the #GVariant 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 +#GVariant, 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 #GActionGroup + + + + 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 g_action_group_get_action_state_type(). + +The return value (if non-%NULL) should be freed with +g_variant_unref() when it is no longer required. + + + the current state of the action + + + + + a #GActionGroup + + + + 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 #GVariant array is returned then each item in the array is a +possible value for the state. If a #GVariant 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 +g_variant_unref() when it is no longer required. + + + the state range hint + + + + + a #GActionGroup + + + + 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 +#GVariantType of the state. All calls to +g_action_group_change_action_state() must give a #GVariant of this +type and g_action_group_get_action_state() will return a #GVariant +of the same type. + +If the action is not stateful then this function will return %NULL. +In that case, g_action_group_get_action_state() will return %NULL +and you must not call g_action_group_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 #GActionGroup + + + + the name of the action to query + + + + + + Checks if the named action exists within @action_group. + + + whether the named action exists + + + + + a #GActionGroup + + + + the name of the action to check for + + + + + + Lists the actions contained within @action_group. + +The caller is responsible for freeing the list with g_strfreev() when +it is no longer required. + + + a %NULL-terminated array of the names of the +actions in the group + + + + + + + a #GActionGroup + + + + + + Queries all aspects of the named action within an @action_group. + +This function acquires the information available from +g_action_group_has_action(), g_action_group_get_action_enabled(), +g_action_group_get_action_parameter_type(), +g_action_group_get_action_state_type(), +g_action_group_get_action_state_hint() and +g_action_group_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 +#GActionGroup 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 #GActionGroup + + + + 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 #GActionGroup::action-added signal on @action_group. + +This function should only be called by #GActionGroup implementations. + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + + + Emits the #GActionGroup::action-enabled-changed signal on @action_group. + +This function should only be called by #GActionGroup implementations. + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + whether or not the action is now enabled + + + + + + Emits the #GActionGroup::action-removed signal on @action_group. + +This function should only be called by #GActionGroup implementations. + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + + + Emits the #GActionGroup::action-state-changed signal on @action_group. + +This function should only be called by #GActionGroup implementations. + + + + + + + a #GActionGroup + + + + 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 +g_action_group_get_action_parameter_type(). + + + + + + + a #GActionGroup + + + + 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 g_action_group_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 g_action_group_get_action_state_hint(). + +If the @value GVariant is floating, it is consumed. + + + + + + + a #GActionGroup + + + + 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 or not the action is currently enabled + + + + + a #GActionGroup + + + + 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 g_action_group_activate_action(), +the #GVariant 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 +#GVariant, 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 #GActionGroup + + + + 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 g_action_group_get_action_state_type(). + +The return value (if non-%NULL) should be freed with +g_variant_unref() when it is no longer required. + + + the current state of the action + + + + + a #GActionGroup + + + + 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 #GVariant array is returned then each item in the array is a +possible value for the state. If a #GVariant 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 +g_variant_unref() when it is no longer required. + + + the state range hint + + + + + a #GActionGroup + + + + 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 +#GVariantType of the state. All calls to +g_action_group_change_action_state() must give a #GVariant of this +type and g_action_group_get_action_state() will return a #GVariant +of the same type. + +If the action is not stateful then this function will return %NULL. +In that case, g_action_group_get_action_state() will return %NULL +and you must not call g_action_group_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 #GActionGroup + + + + the name of the action to query + + + + + + Checks if the named action exists within @action_group. + + + whether the named action exists + + + + + a #GActionGroup + + + + the name of the action to check for + + + + + + Lists the actions contained within @action_group. + +The caller is responsible for freeing the list with g_strfreev() when +it is no longer required. + + + a %NULL-terminated array of the names of the +actions in the group + + + + + + + a #GActionGroup + + + + + + Queries all aspects of the named action within an @action_group. + +This function acquires the information available from +g_action_group_has_action(), g_action_group_get_action_enabled(), +g_action_group_get_action_parameter_type(), +g_action_group_get_action_state_type(), +g_action_group_get_action_state_hint() and +g_action_group_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 +#GActionGroup 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 #GActionGroup + + + + 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 or not + + + + + + 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 #GActionGroup. + + + + + + + + + whether the named action exists + + + + + a #GActionGroup + + + + the name of the action to check for + + + + + + + + + + a %NULL-terminated array of the names of the +actions in the group + + + + + + + a #GActionGroup + + + + + + + + + + whether or not the action is currently enabled + + + + + a #GActionGroup + + + + the name of the action to query + + + + + + + + + + the parameter type + + + + + a #GActionGroup + + + + the name of the action to query + + + + + + + + + + the state type, if the action is stateful + + + + + a #GActionGroup + + + + the name of the action to query + + + + + + + + + + the state range hint + + + + + a #GActionGroup + + + + the name of the action to query + + + + + + + + + + the current state of the action + + + + + a #GActionGroup + + + + the name of the action to query + + + + + + + + + + + + + + a #GActionGroup + + + + the name of the action to request the change on + + + + the new state + + + + + + + + + + + + + + a #GActionGroup + + + + the name of the action to activate + + + + parameters to the activation + + + + + + + + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + + + + + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + + + + + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + whether or not the action is now enabled + + + + + + + + + + + + + + a #GActionGroup + + + + the name of an action in the group + + + + the new state of the named action + + + + + + + + + + %TRUE if the action exists, else %FALSE + + + + + a #GActionGroup + + + + 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 #GAction. + + + + + + + + + the name of the action + + + + + a #GAction + + + + + + + + + + the parameter type + + + + + a #GAction + + + + + + + + + + the state type, if the action is stateful + + + + + a #GAction + + + + + + + + + + the state range hint + + + + + a #GAction + + + + + + + + + + whether the action is enabled + + + + + a #GAction + + + + + + + + + + the current state of the action + + + + + a #GAction + + + + + + + + + + + + + + a #GAction + + + + the new state + + + + + + + + + + + + + + a #GAction + + + + the parameter to the activation + + + + + + + + The GActionMap interface is implemented by #GActionGroup +implementations that operate by containing a number of +named #GAction instances, such as #GSimpleActionGroup. + +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. + + + + + + + a #GActionMap + + + + a #GAction + + + + + + Looks up the action with the name @action_name in @action_map. + +If no such action exists, returns %NULL. + + + a #GAction, or %NULL + + + + + a #GActionMap + + + + 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. + + + + + + + a #GActionMap + + + + 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. + + + + + + + a #GActionMap + + + + a #GAction + + + + + + A convenience function for creating multiple #GSimpleAction instances +and adding them to a #GActionMap. + +Each action is constructed as per one #GActionEntry. + +|[<!-- language="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); +} +]| + + + + + + + a #GActionMap + + + + a pointer to + the first item in an array of #GActionEntry 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 #GAction, or %NULL + + + + + a #GActionMap + + + + 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. + + + + + + + a #GActionMap + + + + the name of the action + + + + + + + The virtual function table for #GActionMap. + + + + + + + + + a #GAction, or %NULL + + + + + a #GActionMap + + + + the name of an action + + + + + + + + + + + + + + a #GActionMap + + + + a #GAction + + + + + + + + + + + + + + a #GActionMap + + + + the name of the action + + + + + + + + #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 g_file_get_path()) when using g_app_info_launch() even if +the application requested an URI and not a POSIX path. For example +for an desktop-file based application with Exec key `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 #GFile constructors (since gvfs +implements the #GVfs extension point). As such, if the application +needs to examine the URI, it needs to use g_file_get_uri() or +similar on #GFile. In other words, an application cannot assume +that the URI passed to e.g. g_file_new_for_commandline_arg() is +equal to the result of g_file_get_uri(). The following snippet +illustrates this: + +|[ +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 #GAppInfo 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 for exact quoting rules. + + + new #GAppInfo for given command. + + + + + the commandline to use + + + + the application name, or %NULL to use @commandline + + + + flags that can specify details of the created #GAppInfo + + + + + + Gets a list of all of the applications currently registered +on this system. + +For desktop files, this includes applications that have +`NoDisplay=true` set or are excluded from display by means +of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). +The returned list does not include applications which have +the `Hidden` key set. + + + a newly allocated #GList of references to #GAppInfos. + + + + + + + Gets a list of all #GAppInfos for a given content type, +including the recommended and fallback #GAppInfos. See +g_app_info_get_recommended_for_type() and +g_app_info_get_fallback_for_type(). + + + #GList of #GAppInfos + for given @content_type or %NULL on error. + + + + + + + the content type to find a #GAppInfo for + + + + + + Gets the default #GAppInfo for a given content type. + + + #GAppInfo for given @content_type or + %NULL on error. + + + + + the content type to find a #GAppInfo for + + + + if %TRUE, the #GAppInfo is expected to + support URIs + + + + + + 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". + + + #GAppInfo for given @uri_scheme or %NULL on error. + + + + + a string containing a URI scheme. + + + + + + Gets a list of fallback #GAppInfos for a given content type, i.e. +those applications which claim to support the given content type +by MIME type subclassing and not directly. + + + #GList of #GAppInfos + for given @content_type or %NULL on error. + + + + + + + the content type to find a #GAppInfo for + + + + + + Gets a list of recommended #GAppInfos 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 g_app_info_set_as_last_used_for_type() has been +called. + + + #GList of #GAppInfos + for given @content_type or %NULL on error. + + + + + + + the content type to find a #GAppInfo 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 +g_app_info_launch_default_for_uri_async() instead. + + + %TRUE on success, %FALSE on error. + + + + + the uri to show + + + + an optional #GAppLaunchContext + + + + + + Async version of g_app_info_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 + + + + an optional #GAppLaunchContext + + + + a #GCancellable + + + + a #GAsyncReadyCallback 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 + + + + + a #GAsyncResult + + + + + + Removes all changes to the type associations done by +g_app_info_set_as_default_for_type(), +g_app_info_set_as_default_for_extension(), +g_app_info_add_supports_type() or +g_app_info_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. + + + + + a #GAppInfo. + + + + a string. + + + + + + Obtains the information whether the #GAppInfo can be deleted. +See g_app_info_delete(). + + + %TRUE if @appinfo can be deleted + + + + + a #GAppInfo + + + + + + 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. + + + + + a #GAppInfo. + + + + + + Tries to delete a #GAppInfo. + +On some platforms, there may be a difference between user-defined +#GAppInfos which can be deleted, and system-wide ones which cannot. +See g_app_info_can_delete(). + + + %TRUE if @appinfo has been deleted + + + + + a #GAppInfo + + + + + + Creates a duplicate of a #GAppInfo. + + + a duplicate of @appinfo. + + + + + a #GAppInfo. + + + + + + Checks if two #GAppInfos are equal. + +Note that the check <emphasis>may not</emphasis> 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 #GAppInfo. + + + + the second #GAppInfo. + + + + + + + + + + + + + + + + + Gets a human-readable description of an installed application. + + + a string containing a description of the +application @appinfo, or %NULL if none. + + + + + a #GAppInfo. + + + + + + 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. + + + + + a #GAppInfo. + + + + + + + + + + + + + + + + + Gets the icon for the application. + + + the default #GIcon for @appinfo or %NULL +if there is no default icon. + + + + + a #GAppInfo. + + + + + + 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. + + + + + a #GAppInfo. + + + + + + Gets the installed name of the application. + + + the name of the application for @appinfo. + + + + + a #GAppInfo. + + + + + + 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 +g_app_info_add_supports_type(), but only those exported directly by +the application. + + + + a list of content types. + + + + + + + a #GAppInfo 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 +g_app_info_launch_uris() instead. + +The launched application inherits the environment of the launching +process, but it can be modified with g_app_launch_context_setenv() +and g_app_launch_context_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` and +`DESKTOP_STARTUP_ID` environment variables are also set, based +on information provided in @context. + + + %TRUE on successful launch, %FALSE otherwise. + + + + + a #GAppInfo + + + + a #GList of #GFile objects + + + + + + a #GAppLaunchContext or %NULL + + + + + + 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. + +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. + + + + + a #GAppInfo + + + + a #GList containing URIs to launch. + + + + + + a #GAppLaunchContext or %NULL + + + + + + Async version of g_app_info_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 +g_app_info_launch_default_for_uri_async(). + + + + + + + a #GAppInfo + + + + a #GList containing URIs to launch. + + + + + + a #GAppLaunchContext or %NULL + + + + a #GCancellable + + + + a #GAsyncReadyCallback to call when the request is done + + + + data to pass to @callback + + + + + + Finishes a g_app_info_launch_uris_async() operation. + + + %TRUE on successful launch, %FALSE otherwise. + + + + + a #GAppInfo + + + + a #GAsyncResult + + + + + + Removes a supported type from an application, if possible. + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + a string. + + + + + + Sets the application as the default handler for the given file extension. + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + 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. + + + + + a #GAppInfo. + + + + 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 g_app_info_get_recommended_for_type(), regardless of the default +application for that content type. + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + 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. + + + + + a #GAppInfo. + + + + + + Checks if the application accepts files as arguments. + + + %TRUE if the @appinfo supports files. + + + + + a #GAppInfo. + + + + + + Checks if the application supports reading files and directories from URIs. + + + %TRUE if the @appinfo supports URIs. + + + + + a #GAppInfo. + + + + + + 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. + + + + + a #GAppInfo. + + + + a string. + + + + + + Obtains the information whether the #GAppInfo can be deleted. +See g_app_info_delete(). + + + %TRUE if @appinfo can be deleted + + + + + a #GAppInfo + + + + + + 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. + + + + + a #GAppInfo. + + + + + + Tries to delete a #GAppInfo. + +On some platforms, there may be a difference between user-defined +#GAppInfos which can be deleted, and system-wide ones which cannot. +See g_app_info_can_delete(). + + + %TRUE if @appinfo has been deleted + + + + + a #GAppInfo + + + + + + Creates a duplicate of a #GAppInfo. + + + a duplicate of @appinfo. + + + + + a #GAppInfo. + + + + + + Checks if two #GAppInfos are equal. + +Note that the check <emphasis>may not</emphasis> 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 #GAppInfo. + + + + the second #GAppInfo. + + + + + + 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 + + + + + a #GAppInfo + + + + + + Gets a human-readable description of an installed application. + + + a string containing a description of the +application @appinfo, or %NULL if none. + + + + + a #GAppInfo. + + + + + + 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. + + + + + a #GAppInfo. + + + + + + Gets the executable's name for the installed application. + + + a string containing the @appinfo's application +binaries name + + + + + a #GAppInfo + + + + + + Gets the icon for the application. + + + the default #GIcon for @appinfo or %NULL +if there is no default icon. + + + + + a #GAppInfo. + + + + + + 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. + + + + + a #GAppInfo. + + + + + + Gets the installed name of the application. + + + the name of the application for @appinfo. + + + + + a #GAppInfo. + + + + + + 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 +g_app_info_add_supports_type(), but only those exported directly by +the application. + + + + a list of content types. + + + + + + + a #GAppInfo 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 +g_app_info_launch_uris() instead. + +The launched application inherits the environment of the launching +process, but it can be modified with g_app_launch_context_setenv() +and g_app_launch_context_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` and +`DESKTOP_STARTUP_ID` environment variables are also set, based +on information provided in @context. + + + %TRUE on successful launch, %FALSE otherwise. + + + + + a #GAppInfo + + + + a #GList of #GFile objects + + + + + + a #GAppLaunchContext or %NULL + + + + + + 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. + +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. + + + + + a #GAppInfo + + + + a #GList containing URIs to launch. + + + + + + a #GAppLaunchContext or %NULL + + + + + + Async version of g_app_info_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 +g_app_info_launch_default_for_uri_async(). + + + + + + + a #GAppInfo + + + + a #GList containing URIs to launch. + + + + + + a #GAppLaunchContext or %NULL + + + + a #GCancellable + + + + a #GAsyncReadyCallback to call when the request is done + + + + data to pass to @callback + + + + + + Finishes a g_app_info_launch_uris_async() operation. + + + %TRUE on successful launch, %FALSE otherwise. + + + + + a #GAppInfo + + + + a #GAsyncResult + + + + + + Removes a supported type from an application, if possible. + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + a string. + + + + + + Sets the application as the default handler for the given file extension. + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + 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. + + + + + a #GAppInfo. + + + + 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 g_app_info_get_recommended_for_type(), regardless of the default +application for that content type. + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + 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. + + + + + a #GAppInfo. + + + + + + Checks if the application accepts files as arguments. + + + %TRUE if the @appinfo supports files. + + + + + a #GAppInfo. + + + + + + Checks if the application supports reading files and directories from URIs. + + + %TRUE if the @appinfo supports URIs. + + + + + a #GAppInfo. + + + + + + + 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. + + + + + + + a duplicate of @appinfo. + + + + + a #GAppInfo. + + + + + + + + + + %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + + + + + the first #GAppInfo. + + + + the second #GAppInfo. + + + + + + + + + + a string containing the application's ID. + + + + + a #GAppInfo. + + + + + + + + + + the name of the application for @appinfo. + + + + + a #GAppInfo. + + + + + + + + + + a string containing a description of the +application @appinfo, or %NULL if none. + + + + + a #GAppInfo. + + + + + + + + + + + + + + + + + + + + + + + the default #GIcon for @appinfo or %NULL +if there is no default icon. + + + + + a #GAppInfo. + + + + + + + + + + %TRUE on successful launch, %FALSE otherwise. + + + + + a #GAppInfo + + + + a #GList of #GFile objects + + + + + + a #GAppLaunchContext or %NULL + + + + + + + + + + %TRUE if the @appinfo supports URIs. + + + + + a #GAppInfo. + + + + + + + + + + %TRUE if the @appinfo supports files. + + + + + a #GAppInfo. + + + + + + + + + + %TRUE on successful launch, %FALSE otherwise. + + + + + a #GAppInfo + + + + a #GList containing URIs to launch. + + + + + + a #GAppLaunchContext or %NULL + + + + + + + + + + %TRUE if the @appinfo should be shown, %FALSE otherwise. + + + + + a #GAppInfo. + + + + + + + + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + the content type. + + + + + + + + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + a string containing the file extension + (without the dot). + + + + + + + + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + a string. + + + + + + + + + + %TRUE if it is possible to remove supported + content types from a given @appinfo, %FALSE if not. + + + + + a #GAppInfo. + + + + + + + + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + a string. + + + + + + + + + + %TRUE if @appinfo can be deleted + + + + + a #GAppInfo + + + + + + + + + + %TRUE if @appinfo has been deleted + + + + + a #GAppInfo + + + + + + + + + + + + + + + + + + + + + + + the display name of the application for @appinfo, or the name if +no display name is available. + + + + + a #GAppInfo. + + + + + + + + + + %TRUE on success, %FALSE on error. + + + + + a #GAppInfo. + + + + the content type. + + + + + + + + + + + a list of content types. + + + + + + + a #GAppInfo that can handle files + + + + + + + + + + + + + + a #GAppInfo + + + + a #GList containing URIs to launch. + + + + + + a #GAppLaunchContext or %NULL + + + + a #GCancellable + + + + a #GAsyncReadyCallback to call when the request is done + + + + data to pass to @callback + + + + + + + + + + %TRUE on successful launch, %FALSE otherwise. + + + + + a #GAppInfo + + + + a #GAsyncResult + + + + + + + + #GAppInfoMonitor is a very simple object used for monitoring the app +info database for changes (ie: newly installed or removed +applications). + +Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect +to the "changed" signal. + +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 data is actually required. The exception to this case is when +application information is actually being displayed on the screen +(eg: 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. + +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 for changes (ie: newly installed +or removed applications). + + + + + + + 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. + + + a #GAppLaunchContext. + + + + + 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. + + + + + a #GAppLaunchContext + + + + a #GAppInfo + + + + a #GList of #GFile objects + + + + + + + + Initiates startup notification for the application and returns the +`DESKTOP_STARTUP_ID` for the launched operation, if supported. + +Startup notification IDs are defined in the +[FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"). + + + a startup notification ID for the application, or %NULL if + not supported. + + + + + a #GAppLaunchContext + + + + a #GAppInfo + + + + a #GList of of #GFile objects + + + + + + + + Called when an application has failed to launch, so that it can cancel +the application startup notification started in g_app_launch_context_get_startup_notify_id(). + + + + + + + a #GAppLaunchContext. + + + + the startup notification id that was returned by g_app_launch_context_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. + + + + + a #GAppLaunchContext + + + + a #GAppInfo + + + + a #GList of #GFile 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 + + + + + + + a #GAppLaunchContext + + + + + + Initiates startup notification for the application and returns the +`DESKTOP_STARTUP_ID` for the launched operation, if supported. + +Startup notification IDs are defined in the +[FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"). + + + a startup notification ID for the application, or %NULL if + not supported. + + + + + a #GAppLaunchContext + + + + a #GAppInfo + + + + a #GList of of #GFile objects + + + + + + + + Called when an application has failed to launch, so that it can cancel +the application startup notification started in g_app_launch_context_get_startup_notify_id(). + + + + + + + a #GAppLaunchContext. + + + + the startup notification id that was returned by g_app_launch_context_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. + + + + + + + a #GAppLaunchContext + + + + 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. + + + + + + + a #GAppLaunchContext + + + + the environment variable to remove + + + + + + + + + + + + The ::launch-failed signal is emitted when a #GAppInfo launch +fails. The startup notification id is provided, so that the launcher +can cancel the startup notification. + + + + + + the startup notification id for the failed launch + + + + + + The ::launched signal is emitted when a #GAppInfo is successfully +launched. 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. + + + + + + the #GAppInfo that was just launched + + + + additional platform-specific data for this launch + + + + + + + + + + + + + + + a display string for the display. + + + + + a #GAppLaunchContext + + + + a #GAppInfo + + + + a #GList of #GFile objects + + + + + + + + + + + + a startup notification ID for the application, or %NULL if + not supported. + + + + + a #GAppLaunchContext + + + + a #GAppInfo + + + + a #GList of of #GFile objects + + + + + + + + + + + + + + + + a #GAppLaunchContext. + + + + the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 g_application_hold() and g_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 +the 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 g_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 g_application_run() promptly returns. See the code +examples below. + +If used, the expected form of an application identifier is the same as +that of 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 g_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 +g_application_register()). Unfortunately, this means that you cannot use +g_application_get_is_remote() to decide if you want to register object paths. + +GApplication also implements the #GActionGroup and #GActionMap +interfaces and lets you easily export actions by adding them with +g_action_map_add_action(). When invoking an action by calling +g_action_group_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 #GDBusActionGroup wrapper to +conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper +for remote access to exported #GMenuModels. + +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 #GApplication::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 +#GVariant dictionary mapping strings to variants. To use platform +data, override the @before_emit or @after_emit virtual functions +in your #GApplication subclass. When dealing with +#GApplicationCommandLine objects, the platform data is +directly available via g_application_command_line_get_cwd(), +g_application_command_line_get_environ() and +g_application_command_line_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 @add_platform_data +virtual function. For instance, #GtkApplication adds startup notification +data in this way. + +To parse commandline arguments you may handle the +#GApplication::command-line signal or override the local_command_line() +vfunc, 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://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c). + +For an example of using actions with GApplication, see +[gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c). + +For an example of using extra D-Bus hooks with GApplication, see +[gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. +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 unrecognised options will be +treated as errors. Unrecognised 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 &as +- for %G_OPTION_ARG_FILENAME_ARRAY, use ^aay + + + + + + + a #GApplication + + + + a + %NULL-terminated list of #GOptionEntrys + + + + + + + + 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 unrecognised 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 currenty 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 + + + + + + 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(). + + + + + + + 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][gapplication-example-cmdline2] +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 +g_application_withdraw_notification(). + + + + + + + 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][gresource] 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 + + + + + + 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 + + + + + + + + + + + + + + + + + + Whether the application is currently marked as busy through +g_application_mark_busy() or g_application_bind_busy_property(). + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + a #GApplication + + + + + + + + + + + + + + a #GApplication + + + + an array of #GFiles to open + + + + + + the length of the @files array + + + + a hint (or ""), but never %NULL + + + + + + + + + + + + + + + + + + + + + + + + + + %TRUE if the commandline has been completely handled + + + + + a #GApplication + + + + array of command line arguments + + + + + + exit status to fill after processing the command line. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GApplicationCommandLine represents a command-line invocation of +an application. It is created by #GApplication and emitted +in the #GApplication::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 #GOptionContext command-line parsing API, +with the g_application_command_line_get_arguments() function. See +[gapplication-example-cmdline3.c][gapplication-example-cmdline3] +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. The +lifecycle of the originally-invoked process is tied to the lifecycle +of this object (ie: the process exits when the last reference is +dropped). + +The main use for #GApplicationCommandLine (and the +#GApplication::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 +#GApplication::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. +|[<!-- language="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://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c) + +In more complicated cases, the handling of the comandline can be +split between the launcher and the primary instance. +|[<!-- language="C" --> +static gboolean + test_local_cmdline (GApplication *application, + gchar ***arguments, + gint *exit_status) +{ + gint i, j; + gchar **argv; + + argv = *arguments; + + 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 #GApplication::command-line handler which runs in the primary +instance. + +The complete example can be found here: +[gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c) + +If handling the commandline requires a lot of work, it may +be better to defer it. +|[<!-- language="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 #GApplication::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://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c) + + + 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 DBus 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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 there 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. + + + 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. + +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 DBus 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 + + + + + + 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 + + + + + + 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. + + + + + + + a #GApplicationCommandLine + + + + the exit status + + + + + + + + + + + + + + + + + + + + + + + + + The #GApplicationCommandLineClass-struct +contains private data only. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GInputStream for stdin + + + + + a #GApplicationCommandLine + + + + + + + + + + + + + + + + Flags used to define the behaviour of a #GApplication. + + Default + + + 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) + + + + This is the asynchronous version of #GInitable; 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 g_async_initable_new_async() +directly, or indirectly via a foo_thing_new_async() wrapper. This will call +g_async_initable_init_async() under the cover, calling back with %NULL and +a set %GError on failure. + +A typical implementation might look something like this: + +|[<!-- language="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); + + 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][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][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][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][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][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. + + + + + + + + + + + a #GAsyncInitable. + + + + the [I/O priority][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 + + + + + + + + + + %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][g-main-context-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 object the asynchronous operation was started with. + + + + a #GAsyncResult. + + + + user data passed to the callback. + + + + + + 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][g-main-context-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 #GFileEnumerator 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: +|[<!-- language="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 # {#io-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 #GAsyncResult. + + + a new reference to the source + object for the @res, or %NULL if there is none. + + + + + a #GAsyncResult + + + + + + Gets the user data from a #GAsyncResult. + + + the user data for @res. + + + + + a #GAsyncResult. + + + + + + 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 #GAsyncResult + + + + an application-defined tag + + + + + + Gets the source object from a #GAsyncResult. + + + a new reference to the source + object for the @res, or %NULL if there is none. + + + + + a #GAsyncResult + + + + + + Gets the user data from a #GAsyncResult. + + + the user data for @res. + + + + + a #GAsyncResult. + + + + + + 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 #GAsyncResult + + + + an application-defined tag + + + + + + If @res is a #GSimpleAsyncResult, this is equivalent to +g_simple_async_result_propagate_error(). Otherwise it returns +%FALSE. + +This can be used for legacy error handling in async *_finish() +wrapper functions that traditionally handled #GSimpleAsyncResult +error returns themselves rather than calling into the virtual method. +This should not be used in new code; #GAsyncResult 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 #GAsyncResult + + + + + + + Interface definition for #GAsyncResult. + + + The parent interface. + + + + + + + the user data for @res. + + + + + a #GAsyncResult. + + + + + + + + + + a new reference to the source + object for the @res, or %NULL if there is none. + + + + + a #GAsyncResult + + + + + + + + + + %TRUE if @res has the indicated @source_tag, %FALSE if + not. + + + + + a #GAsyncResult + + + + an application-defined tag + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Buffered input stream implements #GFilterInputStream and provides +for buffered reads. + +By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. + +To create a buffered input stream, use g_buffered_input_stream_new(), +or g_buffered_input_stream_new_sized() to specify the buffer's size at +construction. + +To get the size of a buffer within a buffered input stream, use +g_buffered_input_stream_get_buffer_size(). To change the size of a +buffered input stream's buffer, use +g_buffered_input_stream_set_buffer_size(). Note that the buffer's size +cannot be reduced below the size of the data within the buffer. + + + + Creates a new #GInputStream from the given @base_stream, with +a buffer set to the default size (4 kilobytes). + + + a #GInputStream for the given @base_stream. + + + + + a #GInputStream + + + + + + Creates a new #GBufferedInputStream from the given @base_stream, +with a buffer set to @size. + + + a #GInputStream. + + + + + a #GInputStream + + + + 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 %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. + +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 %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. + +For the asynchronous, non-blocking, version of this function, see +g_buffered_input_stream_fill_async(). + + + the number of bytes read into @stream's buffer, up to @count, + or -1 on error. + + + + + a #GBufferedInputStream + + + + the number of bytes that will be read from the stream + + + + optional #GCancellable 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 g_buffered_input_stream_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 #GBufferedInputStream + + + + the number of bytes that will be read from the stream + + + + the [I/O priority][io-priority] of the request + + + + optional #GCancellable object + + + + a #GAsyncReadyCallback + + + + a #gpointer + + + + + + Finishes an asynchronous read. + + + a #gssize of the read stream, or `-1` on an error. + + + + + a #GBufferedInputStream + + + + a #GAsyncResult + + + + + + 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 %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. + +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 %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. + +For the asynchronous, non-blocking, version of this function, see +g_buffered_input_stream_fill_async(). + + + the number of bytes read into @stream's buffer, up to @count, + or -1 on error. + + + + + a #GBufferedInputStream + + + + the number of bytes that will be read from the stream + + + + optional #GCancellable 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 g_buffered_input_stream_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 #GBufferedInputStream + + + + the number of bytes that will be read from the stream + + + + the [I/O priority][io-priority] of the request + + + + optional #GCancellable object + + + + a #GAsyncReadyCallback + + + + a #gpointer + + + + + + Finishes an asynchronous read. + + + a #gssize of the read stream, or `-1` on an error. + + + + + a #GBufferedInputStream + + + + a #GAsyncResult + + + + + + Gets the size of the available data within the stream. + + + size of the available stream. + + + + + #GBufferedInputStream + + + + + + Gets the size of the input buffer. + + + the current buffer size. + + + + + a #GBufferedInputStream + + + + + + Peeks in the buffer, copying data of size @count into @buffer, +offset @offset bytes. + + + a #gsize of the number of bytes peeked, or -1 on error. + + + + + a #GBufferedInputStream + + + + a pointer to + an allocated chunk of memory + + + + + + a #gsize + + + + a #gsize + + + + + + 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 #GBufferedInputStream + + + + 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 %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. + + + the byte read from the @stream, or -1 on end of stream or error. + + + + + a #GBufferedInputStream + + + + optional #GCancellable 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 #GBufferedInputStream + + + + a #gsize + + + + + + + + + + + + + + + + + + + + + + + + the number of bytes read into @stream's buffer, up to @count, + or -1 on error. + + + + + a #GBufferedInputStream + + + + the number of bytes that will be read from the stream + + + + optional #GCancellable object, %NULL to ignore + + + + + + + + + + + + + + a #GBufferedInputStream + + + + the number of bytes that will be read from the stream + + + + the [I/O priority][io-priority] of the request + + + + optional #GCancellable object + + + + a #GAsyncReadyCallback + + + + a #gpointer + + + + + + + + + + a #gssize of the read stream, or `-1` on an error. + + + + + a #GBufferedInputStream + + + + a #GAsyncResult + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Buffered output stream implements #GFilterOutputStream and provides +for buffered writes. + +By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes. + +To create a buffered output stream, use g_buffered_output_stream_new(), +or g_buffered_output_stream_new_sized() to specify the buffer's size +at construction. + +To get the size of a buffer within a buffered input stream, use +g_buffered_output_stream_get_buffer_size(). To change the size of a +buffered output stream's buffer, use +g_buffered_output_stream_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 #GOutputStream for the given @base_stream. + + + + + a #GOutputStream. + + + + + + Creates a new buffered output stream with a given buffer size. + + + a #GOutputStream with an internal buffer set to @size. + + + + + a #GOutputStream. + + + + a #gsize. + + + + + + Checks if the buffer automatically grows as data is added. + + + %TRUE if the @stream's buffer automatically grows, +%FALSE otherwise. + + + + + a #GBufferedOutputStream. + + + + + + Gets the size of the buffer in the @stream. + + + the current size of the buffer. + + + + + a #GBufferedOutputStream. + + + + + + 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 #GBufferedOutputStream. + + + + a #gboolean. + + + + + + Sets the size of the internal buffer to @size. + + + + + + + a #GBufferedOutputStream. + + + + a #gsize. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Invoked when a connection to a message bus has been obtained. + + + + + + + The #GDBusConnection to a message bus. + + + + The name that is requested to be owned. + + + + User data passed to g_bus_own_name(). + + + + + + Invoked when the name is acquired. + + + + + + + The #GDBusConnection on which to acquired the name. + + + + The name being owned. + + + + User data passed to g_bus_own_name() or g_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 #GDBusConnection on which to acquire the name or %NULL if +the connection was disconnected. + + + + The name being owned. + + + + User data passed to g_bus_own_name() or g_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 g_bus_own_name() rather than entering the waiting queue for that name. (Since 2.54) + + + + 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. + + + a #GIcon for the given + @bytes, or %NULL on error. + + + + + a #GBytes. + + + + + + Gets the #GBytes associated with the given @icon. + + + a #GBytes, or %NULL. + + + + + a #GIcon. + + + + + + The bytes containing the icon. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + 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 at most once, either directly at the +time of the connect if @cancellable is already cancelled, +or when @cancellable is cancelled in some thread. + +@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. g_cancellable_cancel(). + + + 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(). + + + %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. + + + + + + + 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. + + + + + + + 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 #GConverter based on +GIConv. + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + #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 + + + + + + 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. + + + + + + + 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 + + + + + + + + + + + + + + a #GConverter. + + + + + + + + Converter input stream implements #GInputStream and allows +conversion of data of various types during reading. + +As of GLib 2.34, #GConverterInputStream implements +#GPollableInputStream. + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Converter output stream implements #GOutputStream and allows +conversion of data of various types during reading. + +As of GLib 2.34, #GConverterOutputStream implements +#GPollableOutputStream. + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. This information 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. +g_socket_get_credentials(). + +Some operating systems supports securely sending and receiving +credentials over a Unix Domain Socket, see +#GUnixCredentialsMessage, g_unix_connection_send_credentials() and +g_unix_connection_receive_credentials() for details. + +On Linux, the native credential type is a struct ucred - see the +unix(7) man page for details. This corresponds to +%G_CREDENTIALS_TYPE_LINUX_UCRED. + +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. + + + 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 an 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 the +operation 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. + + + The UNIX user identifier or -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 an 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GDBusActionGroup is an implementation of the #GActionGroup +interface that can be used as a proxy for an action group +that is exported over D-Bus with g_dbus_connection_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. + + + + + + + The #GDBusAuthObserver type provides a mechanism for participating +in how a #GDBusServer (or a #GDBusConnection) 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: + +|[<!-- language="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 # {#auth-observer} + +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, you would use a signal handler like the following: + +|[<!-- language="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 #GIOStream. + +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 g_bus_own_name(), +g_bus_watch_name() or g_dbus_proxy_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 g_bus_get() and g_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, g_dbus_connection_new() and +g_bus_get(), and the synchronous versions of those methods, give you an +initialized connection. Language bindings for GIO should use +g_initable_new() or g_async_initable_new_async(), which also initialize the +connection. + +If you construct an uninitialized #GDBusConnection, such as via +g_object_new(), you must initialize it via g_initable_init() or +g_async_initable_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 g_object_unref(). + +## An example D-Bus server # {#gdbus-server} + +Here is an example for a D-Bus server: +[gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c) + +## An example for exporting a subtree # {#gdbus-subtree-server} + +Here is an example for exporting a subtree: +[gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c) + +## An example for file descriptor passing # {#gdbus-unix-fd-client} + +Here is an example for passing UNIX file descriptors: +[gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-unix-fd-client.c) + +## An example for exporting a GObject # {#gdbus-export} + +Here is an example for exporting a #GObject: +[gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/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 or +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS 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 a 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 a 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 or +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS 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][g-main-context-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 #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 #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. + +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(). + + + %NULL if @error is set. Otherwise a #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. + +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 #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][g-main-context-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][g-main-context-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 +g_dbus_connection_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 + + + + + a #GDBusConnection + + + + a D-Bus object path + + + + a #GActionGroup + + + + + + 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). + +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 message to the transport and then flushes the transport +(using g_output_stream_flush_async()). This is useful in programs +that wants to emit a D-Bus signal and then exit immediately. Without +flushing the connection, there is no guaranteed 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][g-main-context-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][g-main-context-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][gdbus-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. + + + 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. + + + + + + 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][g-main-context-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][gdbus-subtree-server] 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. + +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][gdbus-server] and [client][gdbus-unix-fd-client] +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. + +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][g-main-context-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][gdbus-server] and [client][gdbus-unix-fd-client] +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][gdbus-server] and [client][gdbus-unix-fd-client] +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. + +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][gdbus-server] and [client][gdbus-unix-fd-client] +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 with a whenever +the signal is received. Note that @callback will be invoked in the +[thread-default main context][g-main-context-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.) + +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. + + + + + + + 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 +g_dbus_connection_export_action_group(). + +It is an error to call this function with an ID that wasn't returned +from g_dbus_connection_export_action_group() or to call it with the +same ID more than once. + + + + + + + a #GDBusConnection + + + + the ID from g_dbus_connection_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. + + + + 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. + + + + 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 (cf. g_dbus_error_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 #GError using g_dbus_error_new_for_dbus_error(). + +This function is typically only used in object mappings to put a +#GError on the wire. Regular applications should not use it. + + + A D-Bus error name (never %NULL). Free with g_free(). + + + + + A #GError. + + + + + + Gets the D-Bus error name used for @error, if any. + +This function is guaranteed to return a D-Bus error name for all +#GErrors returned from functions handling remote method calls +(e.g. g_dbus_connection_call_finish()) unless +g_dbus_error_strip_remote_error() has been used on @error. + + + an allocated string or %NULL if the D-Bus error name + could not be found. Free with g_free(). + + + + + a #GError + + + + + + Checks if @error represents an error received via D-Bus from a remote peer. If so, +use g_dbus_error_get_remote_error() to get the name of the error. + + + %TRUE if @error represents an error from a remote peer, +%FALSE otherwise. + + + + + A #GError. + + + + + + Creates a #GError based on the contents of @dbus_error_name and +@dbus_error_message. + +Errors registered with g_dbus_error_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 g_dbus_error_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 g_dbus_error_encode_gerror() +the error domain and code encoded in the name is used to +create the #GError. Also, @dbus_error_name is added to the error message +such that it can be recovered with g_dbus_error_get_remote_error(). + +Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR +in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is +added to the error message such that it can be recovered with +g_dbus_error_get_remote_error(). + +In all three cases, @dbus_error_name can always be recovered from the +returned #GError using the g_dbus_error_get_remote_error() function +(unless g_dbus_error_strip_remote_error() hasn't been used on the returned error). + +This function is typically only used in object mappings to prepare +#GError instances for applications. Regular applications should not use +it. + + + An allocated #GError. Free with g_error_free(). + + + + + D-Bus error name. + + + + D-Bus error message. + + + + + + + + + + + Creates an association to map between @dbus_error_name and +#GErrors specified by @error_domain and @error_code. + +This is typically done in the routine that returns the #GQuark for +an error domain. + + + %TRUE if the association was created, %FALSE if it already +exists. + + + + + A #GQuark for a error domain. + + + + An error code. + + + + A D-Bus error name. + + + + + + Helper function for associating a #GError error domain with D-Bus error names. + + + + + + + The error domain name. + + + + A pointer where to store the #GQuark. + + + + A pointer to @num_entries #GDBusErrorEntry struct items. + + + + + + Number of items to register. + + + + + + Does nothing if @error is %NULL. Otherwise sets *@error to +a new #GError created with g_dbus_error_new_for_dbus_error() +with @dbus_error_message prepend with @format (unless %NULL). + + + + + + + A pointer to a #GError or %NULL. + + + + D-Bus error name. + + + + D-Bus error message. + + + + printf()-style format to prepend to @dbus_error_message or %NULL. + + + + Arguments for @format. + + + + + + Like g_dbus_error_set_dbus_error() but intended for language bindings. + + + + + + + A pointer to a #GError or %NULL. + + + + D-Bus error name. + + + + D-Bus error message. + + + + printf()-style format to prepend to @dbus_error_message or %NULL. + + + + 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. + + + + + A #GError. + + + + + + Destroys an association previously set up with g_dbus_error_register_error(). + + + %TRUE if the association was destroyed, %FALSE if it wasn't found. + + + + + A #GQuark for a error domain. + + + + An error code. + + + + A D-Bus error name. + + + + + + + Struct used in g_dbus_error_register_error_domain(). + + + An error code. + + + + The D-Bus error name to associate with @error_code. + + + + + The #GDBusInterface type is the base type for D-Bus interfaces both +on the service side (see #GDBusInterfaceSkeleton) and client side +(see #GDBusProxy). + + + 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_. + + + 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_. + + + 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. + + + + 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. + + + + + + + A #GDBusInterfaceInfo. Do not free. + + + + + An exported D-Bus interface. + + + + + + + + + + A #GDBusObject or %NULL. The returned + reference belongs to @interface_ and should not be freed. + + + + + An exported D-Bus interface + + + + + + + + + + + + + + An exported D-Bus interface. + + + + A #GDBusObject or %NULL. + + + + + + + + + + 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. + + + + + + + A #GDBusConnection. + + + + The unique bus name of the remote caller. + + + + The object path that the method was invoked on. + + + + The D-Bus interface name the method was invoked on. + + + + 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. + + + + 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. + + + + + + + + + + + + + + + + + + + + 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}'][G-VARIANT-TYPE-VARDICT:CAPS]. +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. + + + A #GDBusInterfaceVTable (never %NULL). + + + + + A #GDBusInterfaceSkeleton. + + + + + + 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}'][G-VARIANT-TYPE-VARDICT:CAPS]. +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. + + + A #GDBusInterfaceVTable (never %NULL). + + + + + 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. + + + + + + + A #GDBusInterfaceInfo (never %NULL). Do not free. + + + + + A #GDBusInterfaceSkeleton. + + + + + + + + + + A #GDBusInterfaceVTable (never %NULL). + + + + + A #GDBusInterfaceSkeleton. + + + + + + + + + + A #GVariant of type +['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. +Free with g_variant_unref(). + + + + + A #GDBusInterfaceSkeleton. + + + + + + + + + + + + + + A #GDBusInterfaceSkeleton. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #GMenuModel that can be used +as a proxy for a menu model that is exported over D-Bus with +g_dbus_connection_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 #GDBusConnection. + + 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. + + + The string item or %NULL if the first item in the body of +@message is not a string. + + + + + 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, conncet 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. + + + The value. + + + + + A #GDBusMessage. + + + + + + Gets the UNIX file descriptors associated with @message, if any. + +This method is only available on UNIX. + + + 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 g_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. + + + + + + + A #GDBusMessage. + + + + A #guint32. + + + + + + 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. + + + + + + + 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 an 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 +#GDBusInterfaceVTable that was passed to g_dbus_connection_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. + +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][gdbus-server] and [client][gdbus-unix-fd-client] +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. + + + 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-Simple-XML-Subset-Parser.description]-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 #GDBusObjectSkeleton) and the client side +(see #GDBusObjectProxy). 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + A string owned by @object. Do not free. + + + + + A #GDBusObject. + + + + + + + + + + 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. + + + + + + + + + + %NULL if not found, otherwise a + #GDBusInterface that must be freed with g_object_unref(). + + + + + A #GDBusObject. + + + + A D-Bus interface name. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #GDBusObjectManagerClient for the client-side implementation +and #GDBusObjectManagerServer 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 #GDBusObjectProxy 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #GDBusObjectProxy 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 #GDBusObjectManagerServer (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 #GDBusObjectManager::object-added and +#GDBusObjectManager::object-removed signals and inspect the +#GDBusObjectProxy objects returned by +g_dbus_object_manager_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. g_dbus_object_manager_get_objects() returns the empty list) and +the #GDBusObjectManagerClient: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 #GObject::notify +signal to watch for changes on the #GDBusObjectManagerClient:name-owner +property. When the name owner vanishes, the behavior is that +#GDBusObjectManagerClient:name-owner is set to %NULL (this includes +emission of the #GObject::notify signal) and then +#GDBusObjectManager::object-removed signals are synthesized +for all currently existing object proxies. Since +#GDBusObjectManagerClient: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 +#GDBusObjectManager. Similarly, when a new name owner appears, +#GDBusObjectManager::object-added signals are synthesized +while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all +object proxies have been added, the #GDBusObjectManagerClient:name-owner +is set to the new name owner (this includes emission of the +#GObject::notify signal). Furthermore, you are guaranteed that +#GDBusObjectManagerClient: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 #GDBusProxy +instances. All signals (including the +org.freedesktop.DBus.Properties::PropertiesChanged signal) +delivered to #GDBusProxy 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 +#GDBusObjectProxy and #GDBusProxy objects, the +#GDBusObject::interface-added, +#GDBusObject::interface-removed, +#GDBusProxy::g-properties-changed and +#GDBusProxy::g-signal signals +are also emitted on the #GDBusObjectManagerClient instance managing these +objects. The signals emitted are +#GDBusObjectManager::interface-added, +#GDBusObjectManager::interface-removed, +#GDBusObjectManagerClient::interface-proxy-properties-changed and +#GDBusObjectManagerClient::interface-proxy-signal. + +Note that all callbacks and signals are emitted in the +[thread-default main context][g-main-context-push-thread-default] +that the #GDBusObjectManagerClient object was constructed +in. Additionally, the #GDBusObjectProxy and #GDBusProxy 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][g-main-context-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 loop][g-main-context-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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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][g-main-context-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][g-main-context-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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + A string owned by @manager. Do not free. + + + + + A #GDBusObjectManager. + + + + + + + + + + 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. + + + + + + + + + + A #GDBusObject or %NULL. Free with + g_object_unref(). + + + + + A #GDBusObjectManager. + + + + Object path to look up. + + + + + + + + + + A #GDBusInterface instance or %NULL. Free + with g_object_unref(). + + + + + A #GDBusObjectManager. + + + + Object path to look up. + + + + D-Bus interface name to look up. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GDBusObjectManagerServer is used to export #GDBusObject 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 #GDBusObjectManagerClient 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 #GDBusObjectManagerClient +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 #GDBusObjectManager. + + + + Creates a new #GDBusObjectSkeleton. + + + A #GDBusObjectSkeleton. Free with g_object_unref(). + + + + + An object path. + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 +#GDBusProxyFlags 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 +#GDBusProxy:g-name-owner. Connect to the #GObject::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). + +The generic #GDBusProxy::g-properties-changed and +#GDBusProxy::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][gdbus-example-gdbus-codegen] shows how this can +easily be done using the [gdbus-codegen][gdbus-codegen] tool. + +A #GDBusProxy instance can be used from multiple threads but note +that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed +and #GObject::notify) are emitted in the +[thread-default main context][g-main-context-push-thread-default] +of the thread where the instance was constructed. + +An example using a proxy for a well-known name can be found in +[gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/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][gdbus-wellknown-proxy]. + + + 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][gdbus-wellknown-proxy]. + + + 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][gdbus-wellknown-proxy]. + + + + + + + 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][gdbus-wellknown-proxy]. + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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][g-main-context-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. + + + 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. + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + 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 loop][g-main-context-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. + + + + User data. + + + + + + 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. + +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 g_bus_own_name(). + +An example of peer-to-peer communication with G-DBus can be found +in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/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 #GDBusAuthObserver +that only accepts connections that have successfully authenticated +as the same user that is running the #GDBusServer. + + + 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][gdbus-peer-to-peer]. + +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. + + + 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. + + + 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. + + + + 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][g-main-context-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. + + + + Signature for callback function used in g_dbus_connection_signal_subscribe(). + + + + + + + A #GDBusConnection. + + + + The unique bus name of the sender of the signal. + + + + 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 (never %NULL). + + + + 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 default handler to URI association. See +[Extending GIO][extending-gio]. + The #GDesktopAppInfoLookup interface is deprecated and + unused by GIO. + + + + + + + + + + + + + + + + + + + + + + + + + + The string used to obtain a Unix device path with g_drive_get_identifier(). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Data input stream implements #GInputStream 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][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][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][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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Data output stream implements #GOutputStream 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. + + + + 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 +#GSocket, 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 #GIOStream. + +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 g_datagram_based_condition_check() or +g_datagram_based_condition_wait(). You can also use +g_datagram_based_create_source() and attach it to a #GMainContext 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, #GDatagramBaseds can be either connection oriented (for +example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds 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. + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + a newly allocated #GSource + + + + + a #GDatagramBased + + + + a #GIOCondition mask to monitor + + + + a #GCancellable + + + + + + + + + + the #GIOCondition mask of the current state + + + + + a #GDatagramBased + + + + a #GIOCondition mask to check + + + + + + + + + + %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 + + + + + + #GDesktopAppInfo is an implementation of #GAppInfo 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 when using it. + + + + Creates a new #GDesktopAppInfo 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 #GDesktopAppInfo, or %NULL if no desktop + file with that id exists. + + + + + the desktop file id + + + + + + Creates a new #GDesktopAppInfo. + + + a new #GDesktopAppInfo or %NULL on error. + + + + + the path of a desktop file, in the GLib + filename encoding + + + + + + Creates a new #GDesktopAppInfo. + + + a new #GDesktopAppInfo or %NULL on error. + + + + + an opened #GKeyFile + + + + + + 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 #GDesktopAppInfo +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. + + + a + list of strvs. Free each item with g_strfreev() and free the outer + list with g_free(). + + + + + + + + + the search string to use + + + + + + Sets the name of the desktop that the application is running in. +This is used by g_app_info_should_show() and +g_desktop_app_info_get_show_in() to evaluate the +`OnlyShowIn` and `NotShowIn` +desktop entry fields. + +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 +action" specified by @action_name. + +This corresponds to the "Name" key within the keyfile group for the +action. + + + the locale-specific action name + + + + + a #GDesktopAppInfo + + + + the name of the action as from + g_desktop_app_info_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 #GDesktopAppInfo + + + + the key to look up + + + + + + Gets the categories from the desktop file. + + + The unparsed Categories key from the desktop file; + i.e. no attempt is made to split it by ';' or validate it. + + + + + a #GDesktopAppInfo + + + + + + When @info was created from a known filename, return it. In some +situations such as the #GDesktopAppInfo returned from +g_desktop_app_info_new_from_keyfile(), this function will return %NULL. + + + The full path to the file for @info, + or %NULL if not known. + + + + + a #GDesktopAppInfo + + + + + + Gets the generic name from the destkop file. + + + The value of the GenericName key + + + + + a #GDesktopAppInfo + + + + + + A desktop file is hidden if the Hidden key in it is +set to True. + + + %TRUE if hidden, %FALSE otherwise. + + + + + a #GDesktopAppInfo. + + + + + + Gets the keywords from the desktop file. + + + The value of the Keywords key + + + + + + + a #GDesktopAppInfo + + + + + + 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 #GDesktopAppInfo + + + + the key to look up + + + + + + Gets the value of the NoDisplay key, which helps determine if the +application info should be shown in menus. See +#G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show(). + + + The value of the NoDisplay key + + + + + a #GDesktopAppInfo + + + + + + 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` and `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 g_app_info_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 #GDesktopAppInfo + + + + 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 #GDesktopAppInfo 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 #GDesktopAppInfo + + + + 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 g_strfreev(). + + + + + + + a #GDesktopAppInfo + + + + 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 #GDesktopAppInfo + + + + the key to look up + + + + + + Activates the named application action. + +You may only call this function on action names that were +returned from g_desktop_app_info_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. + +As with g_app_info_launch() there is no way to detect failures that +occur while using this function. + + + + + + + a #GDesktopAppInfo + + + + the name of the action as from + g_desktop_app_info_list_actions() + + + + a #GAppLaunchContext + + + + + + This function performs the equivalent of g_app_info_launch_uris(), +but is intended primarily for operating system components that +launch applications. Ordinary applications should use +g_app_info_launch_uris(). + +If the application is launched via GSpawn, then @spawn_flags, @user_setup +and @user_setup_data are used for the call to g_spawn_async(). +Additionally, @pid_callback (with @pid_callback_data) will be called to +inform about the PID of the created process. See g_spawn_async_with_pipes() +for information on certain parameter conditions that can enable an +optimized posix_spawn() codepath to be used. + +If application launching occurs via some other mechanism (eg: 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 #GDesktopAppInfo + + + + List of URIs + + + + + + a #GAppLaunchContext + + + + #GSpawnFlags, used for each process + + + + a #GSpawnChildSetupFunc, used once + for each process. + + + + User data for @user_setup + + + + Callback for child processes + + + + User data for @callback + + + + + + Equivalent to g_desktop_app_info_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 #GDesktopAppInfo + + + + List of URIs + + + + + + a #GAppLaunchContext + + + + #GSpawnFlags, used for each process + + + + a #GSpawnChildSetupFunc, 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" 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 #GDesktopAppInfo + + + + + + The origin filename of this #GDesktopAppInfo + + + + + + + + + + + #GDesktopAppInfoLookup is an opaque data structure and can only be accessed +using the following functions. + The #GDesktopAppInfoLookup interface is deprecated and + unused by GIO. + + + Gets the default application for launching applications +using this URI scheme for a particular #GDesktopAppInfoLookup +implementation. + +The #GDesktopAppInfoLookup interface and this function is used +to implement g_app_info_get_default_for_uri_scheme() backends +in a GIO module. There is no reason for applications to use it +directly. Applications should use g_app_info_get_default_for_uri_scheme(). + The #GDesktopAppInfoLookup interface is deprecated and + unused by GIO. + + + #GAppInfo for given @uri_scheme or %NULL on error. + + + + + a #GDesktopAppInfoLookup + + + + a string containing a URI scheme. + + + + + + Gets the default application for launching applications +using this URI scheme for a particular #GDesktopAppInfoLookup +implementation. + +The #GDesktopAppInfoLookup interface and this function is used +to implement g_app_info_get_default_for_uri_scheme() backends +in a GIO module. There is no reason for applications to use it +directly. Applications should use g_app_info_get_default_for_uri_scheme(). + The #GDesktopAppInfoLookup interface is deprecated and + unused by GIO. + + + #GAppInfo for given @uri_scheme or %NULL on error. + + + + + a #GDesktopAppInfoLookup + + + + a string containing a URI scheme. + + + + + + + Interface that is used by backends to associate default +handlers with URI schemes. + + + + + + + + + #GAppInfo for given @uri_scheme or %NULL on error. + + + + + a #GDesktopAppInfoLookup + + + + 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 + + + + + + #GDrive - this represent a piece of hardware connected to the machine. +It's generally only created for removable hardware or hardware with +removable media. + +#GDrive is a container class for #GVolume 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 potententially 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 g_drive_get_start_stop_type(). + +For porting from GnomeVFS 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 capabable of automatically detecting media changes. + + + %TRUE if the @drive is capabable 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. + + + + + + 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 capabable of automatically detecting media changes. + + + %TRUE if the @drive is capabable 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a string containing @drive's name. The returned + string should be freed when no longer needed. + + + + + a #GDrive. + + + + + + + + + + #GIcon for the @drive. + Free the returned object with g_object_unref(). + + + + + a #GDrive. + + + + + + + + + + %TRUE if the @drive contains volumes, %FALSE otherwise. + + + + + a #GDrive. + + + + + + + + + + #GList containing any #GVolume objects on the given @drive. + + + + + + + a #GDrive. + + + + + + + + + + %TRUE if @drive supports removable media, %FALSE otherwise. + + + + + a #GDrive. + + + + + + + + + + %TRUE if @drive has media, %FALSE otherwise. + + + + + a #GDrive. + + + + + + + + + + %TRUE if the @drive is capabable of automatically detecting + media changes, %FALSE otherwise. + + + + + a #GDrive. + + + + + + + + + + %TRUE if the @drive can be ejected, %FALSE otherwise. + + + + + a #GDrive. + + + + + + + + + + %TRUE if the @drive can be polled for media changes, + %FALSE otherwise. + + + + + 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 + + + + + + + + + + %TRUE if the drive has been ejected successfully, + %FALSE otherwise. + + + + + a #GDrive. + + + + a #GAsyncResult. + + + + + + + + + + + + + + a #GDrive. + + + + optional #GCancellable object, %NULL to ignore. + + + + a #GAsyncReadyCallback, or %NULL. + + + + user data to pass to @callback + + + + + + + + + + %TRUE if the drive has been poll_for_mediaed successfully, + %FALSE otherwise. + + + + + a #GDrive. + + + + a #GAsyncResult. + + + + + + + + + + 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 + + + + + + + + + + a %NULL-terminated + array of strings containing kinds of identifiers. Use g_strfreev() + to free. + + + + + + + a #GDrive + + + + + + + + + + A value from the #GDriveStartStopType enumeration. + + + + + a #GDrive. + + + + + + + + + + %TRUE if the @drive can be started, %FALSE otherwise. + + + + + a #GDrive. + + + + + + + + + + %TRUE if the @drive can be started degraded, %FALSE otherwise. + + + + + a #GDrive. + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the drive has been started successfully, + %FALSE otherwise. + + + + + a #GDrive. + + + + a #GAsyncResult. + + + + + + + + + + %TRUE if the @drive can be stopped, %FALSE otherwise. + + + + + a #GDrive. + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the drive has been stopped successfully, + %FALSE otherwise. + + + + + a #GDrive. + + + + a #GAsyncResult. + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + %TRUE if the drive was successfully ejected. %FALSE otherwise. + + + + + a #GDrive. + + + + a #GAsyncResult. + + + + + + + + + + Sorting key for @drive or %NULL if no such key is available. + + + + + A #GDrive. + + + + + + + + + + symbolic #GIcon for the @drive. + Free the returned object with g_object_unref(). + + + + + a #GDrive. + + + + + + + + + + %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 <quote>SECURITY + UNLOCK DEVICE</quote> command) + + + + #GDtlsClientConnection is the client-side subclass of +#GDtlsConnection, 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 + + + 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. + + + + + + + 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 all of the +ways indicated here will be rejected unless the application +overrides the default via #GDtlsConnection::accept-certificate. + + + + + vtable for a #GDtlsClientConnection implementation. + + + The parent interface. + + + + + #GDtlsConnection is the base DTLS connection class type, which wraps +a #GDatagramBased and provides DTLS encryption on top of it. Its +subclasses, #GDtlsClientConnection and #GDtlsServerConnection, +implement client-side and server-side DTLS, respectively. + +For TLS support, see #GTlsConnection. + +As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased, +presenting a datagram-socket-like API for the encrypted connection. This +operates over a base datagram connection, which is also a #GDatagramBased +(#GDtlsConnection:base-socket). + +To close a DTLS connection, use g_dtls_connection_close(). + +Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address +on their base #GDatagramBased if it is a #GSocket — it is up to the caller to +do that if they wish. If they do not, and g_socket_close() is called on the +base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED +error on further I/O. + + + + + + + + + + + + + + + + + + + + + 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 (or after sending a "STARTTLS"-type command) and may +need to rehandshake later if the server requests it, +#GDtlsConnection will handle this for you automatically when you try +to send or receive data on the connection. However, you can call +g_dtls_connection_handshake() manually if you want to know for sure +whether the initial handshake succeeded or failed (as opposed to +just immediately trying to write to @conn, in which +case if it fails, it may not be possible to tell if it failed +before or after completing the handshake). + +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. + +If TLS 1.2 or older is in use, you may call +g_dtls_connection_handshake() after the initial handshake to +rehandshake; however, this usage is deprecated because rehandshaking +is no longer part of the TLS protocol in TLS 1.3. Accordingly, the +behavior of calling this function after the initial handshake is now +undefined, except it is guaranteed to be reasonable and +nondestructive so as to preserve compatibility with code written for +older versions of GLib. + +#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][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][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][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 + + + + + + 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. +(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. (It is not set +during the emission of #GDtlsConnection::accept-certificate.) + + + @conn's peer's certificate errors + + + + + a #GDtlsConnection + + + + + + Gets @conn rehandshaking mode. See +g_dtls_connection_set_rehandshake_mode() for details. + + + @conn's rehandshaking mode + + + + + 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 (or after sending a "STARTTLS"-type command) and may +need to rehandshake later if the server requests it, +#GDtlsConnection will handle this for you automatically when you try +to send or receive data on the connection. However, you can call +g_dtls_connection_handshake() manually if you want to know for sure +whether the initial handshake succeeded or failed (as opposed to +just immediately trying to write to @conn, in which +case if it fails, it may not be possible to tell if it failed +before or after completing the handshake). + +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. + +If TLS 1.2 or older is in use, you may call +g_dtls_connection_handshake() after the initial handshake to +rehandshake; however, this usage is deprecated because rehandshaking +is no longer part of the TLS protocol in TLS 1.3. Accordingly, the +behavior of calling this function after the initial handshake is now +undefined, except it is guaranteed to be reasonable and +nondestructive so as to preserve compatibility with code written for +older versions of GLib. + +#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][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). + + + + + + + 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 + + + + + + Sets how @conn behaves with respect to rehandshaking requests. + +%G_TLS_REHANDSHAKE_NEVER means that it will never agree to +rehandshake after the initial handshake is complete. (For a client, +this means it will refuse rehandshake requests from the server, and +for a server, this means it will close the connection with an error +if the client attempts to rehandshake.) + +%G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a +rehandshake only if the other end of the connection supports the +TLS `renegotiation_info` extension. This is the default behavior, +but means that rehandshaking will not work against older +implementations that do not support that extension. + +%G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow +rehandshaking even without the `renegotiation_info` extension. On +the server side in particular, this is not recommended, since it +leaves the server open to certain attacks. However, this mode is +necessary if you need to allow renegotiation with older client +software. + 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][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 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(). + + + + 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 and the certificate has been accepted. 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-and-ignored 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. + + + + The rehandshaking mode. See +g_dtls_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. + + + + 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. + +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. + + + + + + + + + + + + + + + + + + + + + + + + + + success or failure + + + + + a #GDtlsConnection + + + + a #GCancellable, or %NULL + + + + + + + + + + + + + + a #GDtlsConnection + + + + the [I/O priority][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 + + + + + + + + + + %TRUE on success, %FALSE on failure, in which +case @error will be set. + + + + + a #GDtlsConnection + + + + a #GAsyncResult. + + + + + + + + + + %TRUE on success, %FALSE otherwise + + + + + a #GDtlsConnection + + + + %TRUE to stop reception of incoming datagrams + + + + %TRUE to stop sending outgoing datagrams + + + + a #GCancellable, or %NULL + + + + + + + + + + + + + + a #GDtlsConnection + + + + %TRUE to stop reception of incoming datagrams + + + + %TRUE to stop sending outgoing datagrams + + + + the [I/O priority][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 + + + + + + + + + + %TRUE on success, %FALSE on failure, in which +case @error will be set + + + + + a #GDtlsConnection + + + + a #GAsyncResult + + + + + + + + + + + + + + a #GDtlsConnection + + + + a %NULL-terminated + array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL + + + + + + + + + + + + the negotiated protocol, or %NULL + + + + + a #GDtlsConnection + + + + + + + + #GDtlsServerConnection is the server-side subclass of #GDtlsConnection, +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GEmblem is an implementation of #GIcon that supports +having an emblem, which is an icon with additional properties. +It can than be added to a #GEmblemedIcon. + +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 + + + + + + + + + + + + + + + + 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 #GIcon that supports +adding an emblem to an icon. Adding multiple emblems to an +icon is ensured via g_emblemed_icon_add_emblem(). + +Note that #GEmblemedIcon allows no control over the position +of the emblems. See also #GEmblem 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 of used 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. + + + + + 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 furter 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 UTF8 and can thus be displayed in +the UI. +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. +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 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 getting the path to the 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 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 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 corresponds to the NTFS ctime. + + + + + 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 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. When requested against +items in `trash:///`, will return the date and time when the file +was trashed. 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. When requested against +`trash:///` returns the number of (toplevel) items in the trash folder. +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + + + + + A key in the "trash" namespace. When requested against +items in `trash:///`, will return the original path to the file 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 lstat() +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 number of hard links +for a file. See lstat() 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 device ID for the file +(if it is a special file). See lstat() 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 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. #GFiles 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 #GInputStream and #GOutputStream). + +To construct a #GFile, you can use: +- g_file_new_for_path() if you have a path. +- g_file_new_for_uri() if you have a URI. +- g_file_new_for_commandline_arg() for a command line argument. +- g_file_new_tmp() to create a temporary file from a template. +- g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). +- g_file_new_build_filename() 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 +#GFiles are extensible it could also be something else that corresponds +to a pathname in a userspace implementation of a filesystem. + +#GFiles 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 g_file_get_parent() to get an identifier for the parent +directory, g_file_get_child() to get a child within a directory, +g_file_resolve_relative_path() to resolve a relative path between two +#GFiles. There can be multiple hierarchies, so you may not end up at +the same root if you repeatedly call g_file_get_parent() on two different +files. + +All #GFiles have a basename (get with g_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 g_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 #GFiles 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 #GFiles 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 #GFiles. + +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 #GAsyncReadyCallback which is then used to finalize +the operation, producing a GAsyncResult 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][async-programming] for +more. + +Some #GFile operations almost always take a noticeable amount of time, and +so do not have synchronous analogs. Notable cases include: +- g_file_mount_mountable() to mount a mountable file. +- g_file_unmount_mountable_with_operation() to unmount a mountable file. +- g_file_eject_mountable_with_operation() to eject a mountable file. + +## Entity Tags # {#gfile-etag} + +One notable feature of #GFiles 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 +HTTP 1.1 +[specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) +for HTTP Etag headers, which 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 + + + + + + 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 + + + + + + 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][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][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 function + + + + + + 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][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][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 @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][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, or %NULL + + + + 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, or %NULL + + + + 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. + +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][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. + +Note that two #GFiles that differ can still refer to the same +file on the filesystem due to various forms of filename +aliasing. + +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][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 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 URI for the @file. + +This call does no blocking I/O. + + + a string containing the #GFile's URI. + 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. + +This call does no blocking I/O. + + + a string containing the URI scheme for the given + #GFile. 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. + +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][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 + + + + + + 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][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, or %NULL + + + + 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 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 @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 + + + + + + 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][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 @files's parent, grandparent, etc is @prefix, + %FALSE otherwise. + + + + + input #GFile + + + + input #GFile + + + + + + 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][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 #GFileInfo 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. @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. + +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. + +For symlinks, normally the information about the target of the +symlink is returned, rather than information about the symlink +itself. However if you pass #G_FILE_QUERY_INFO_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 %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 for the given @file, or %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 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][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][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][gfile-etag] + 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][gfile-etag] for the current #GFile, + or %NULL to ignore + + + + %TRUE if a backup should be created + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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][gfile-etag] + 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][gfile-etag] for the current #GFile, + or %NULL to ignore + + + + %TRUE if a backup should be created + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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. + + + #GFile to the resolved path. + %NULL if @relative_path is %NULL or if @file is invalid. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a given relative path string + + + + + + Sets an attribute in the file with attribute name @attribute to @value. + +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][io-priority] of the request + + + + optional #GCancellable object, + %NULL to ignore + + + + a #GAsyncReadyCallback + + + + a #gpointer + + + + + + 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][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 an 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. +Not all file systems support trashing, so this call can return the +%G_IO_ERROR_NOT_SUPPORTED error. + +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][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, or %NULL + + + + 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, or %NULL + + + + 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][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][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 function + + + + + + 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][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][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 @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][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, or %NULL + + + + 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, or %NULL + + + + 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. + +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][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. + +Note that two #GFiles that differ can still refer to the same +file on the filesystem due to various forms of filename +aliasing. + +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][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. + 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. + +This call does no blocking I/O. + + + a string containing the URI scheme for the given + #GFile. 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 @files'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 @content 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 @content 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 @content 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. + +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][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 + + + + + + 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][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, or %NULL + + + + 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 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 @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 + + + + + + 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][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][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. This is +implemented using g_file_query_info() and as such does blocking I/O. + +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][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 #GFileInfo 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. @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. + +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. + +For symlinks, normally the information about the target of the +symlink is returned, rather than information about the symlink +itself. However if you pass #G_FILE_QUERY_INFO_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 %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 for the given @file, or %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 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][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][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][gfile-etag] + 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][gfile-etag] for the current #GFile, + or %NULL to ignore + + + + %TRUE if a backup should be created + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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][gfile-etag] for the document, + or %NULL + + + + %TRUE if a backup should be created + + + + a set of #GFileCreateFlags + + + + a location to a new [entity tag][gfile-etag] + 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 @content 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][gfile-etag] 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][gfile-etag] 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][gfile-etag] + 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][gfile-etag] + 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][gfile-etag] for the current #GFile, + or %NULL to ignore + + + + %TRUE if a backup should be created + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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. + + + #GFile to the resolved path. + %NULL if @relative_path is %NULL or if @file is invalid. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a given relative path string + + + + + + Sets an attribute in the file with attribute name @attribute to @value. + +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][io-priority] of the request + + + + optional #GCancellable object, + %NULL to ignore + + + + a #GAsyncReadyCallback + + + + a #gpointer + + + + + + 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][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 an 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 contexts][g-main-context-push-thread-default-context]. +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. +Not all file systems support trashing, so this call can return the +%G_IO_ERROR_NOT_SUPPORTED error. + +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][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, or %NULL + + + + 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, or %NULL + + + + 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 @attribute 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 a 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 uninitalized 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. + + + + 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. Since 2.20 + + + + #GFileDescriptorBased is implemented by streams (implementations of +#GInputStream or #GOutputStream) 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 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. + + + + + + + The file descriptor + + + + + a #GFileDescriptorBased. + + + + + + + + #GFileEnumerator allows you to operate on a set of #GFiles, +returning a #GFileInfo structure for each file enumerated (e.g. +g_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 +g_file_enumerator_next_file() or its asynchronous version, +g_file_enumerator_next_files_async(). Note that the asynchronous +version will return a list of #GFileInfos, 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 g_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 g_file_enumerator_close(), or +its asynchronous version, g_file_enumerator_close_async(). Once +a #GFileEnumerator is closed, no further actions may be performed +on it, and it should be freed with g_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][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. + +The callback can be called with less than @num_files files in case of error +or at the end of the enumerator. In case of a partial error the callback will +be called with any succeeding items and no error, and on the next request the +error will be reported. If a request is cancelled the callback will be called +with %G_IO_ERROR_CANCELLED. + +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][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][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(). + +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. + +The callback can be called with less than @num_files files in case of error +or at the end of the enumerator. In case of a partial error the callback will +be called with any succeeding items and no error, and on the next request the +error will be reported. If a request is cancelled the callback will be called +with %G_IO_ERROR_CANCELLED. + +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][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. + + + + + + + + + + + + + + + + + + + + + + + + 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][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][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 io streams that both read and write to the same +file handle. + +GFileIOStream implements #GSeekable, which allows the io +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 io stream, use +g_seekable_tell(). + +To find out if a file io stream supports seeking, use g_seekable_can_seek(). +To position a file io stream, use g_seekable_seek(). +To find out if a file io stream supports truncating, use +g_seekable_can_truncate(). To truncate a file io +stream, use g_seekable_truncate(). + +The default implementation of all the #GFileIOStream operations +and the implementation of #GSeekable 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][gio-GIOScheduler] 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_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][gio-GIOScheduler] 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_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][gio-GIOScheduler] 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 #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. + + + + + 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, or %NULL. + + + + + a #GIcon. + + + + + + The file containing the icon. + + + + + + + + An interface for writing VFS file handles. + + + The parent interface. + + + + + + + a new #GFile that is a duplicate + of the given #GFile. + + + + + input #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 + + + + + + + + + + %TRUE if @file1 and @file2 are equal. + + + + + the first #GFile + + + + the second #GFile + + + + + + + + + + %TRUE if @file is native + + + + + input #GFile + + + + + + + + + + %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 + + + + + + + + + + a string containing the URI scheme for the given + #GFile. The returned string should be freed with g_free() + when no longer needed. + + + + + input #GFile + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a string containing the #GFile's URI. + The returned string should be freed with g_free() + when no longer needed. + + + + + input #GFile + + + + + + + + + + a string containing the #GFile's parse name. + The returned string should be freed with g_free() + when no longer needed. + + + + + input #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 + + + + + + + + + + %TRUE if the @files's parent, grandparent, etc is @prefix, + %FALSE otherwise. + + + + + input #GFile + + + + input #GFile + + + + + + + + + + + + + + + + + + + + + + + + + + #GFile to the resolved path. + %NULL if @relative_path is %NULL or if @file is invalid. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a given relative path string + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + + + + + input #GFile + + + + an attribute query string + + + + a set of #GFileQueryInfoFlags + + + + the [I/O priority][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 #GFileEnumerator or %NULL + if an error occurred. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + a #GFileInfo for the given @file, or %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 + + + + + + + + + + + + + + input #GFile + + + + an attribute query string + + + + a set of #GFileQueryInfoFlags + + + + the [I/O priority][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 for given @file + or %NULL on error. Free the returned object with + g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + + + + + input #GFile + + + + an attribute query string + + + + the [I/O priority][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 for given @file + or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + + + + + a #GFile + + + + the [I/O priority][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 + + + + + + + + + + #GMount for given @file or %NULL on error. + Free the returned object with g_object_unref(). + + + + + a #GFile + + + + a #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + + + + + input #GFile + + + + a string + + + + the [I/O priority][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 #GFile or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + %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 + + + + + + + + + + %FALSE if there was any error, %TRUE otherwise. + + + + + input #GFile + + + + a #GFileInfo + + + + #GFileQueryInfoFlags + + + + optional #GCancellable object, + %NULL to ignore + + + + + + + + + + + + + + input #GFile + + + + a #GFileInfo + + + + a #GFileQueryInfoFlags + + + + the [I/O priority][io-priority] of the request + + + + optional #GCancellable object, + %NULL to ignore + + + + a #GAsyncReadyCallback + + + + a #gpointer + + + + + + + + + + %TRUE if the attributes were set correctly, %FALSE otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + a #GFileInfo + + + + + + + + + + #GFileInputStream or %NULL on error. + Free the returned object with g_object_unref(). + + + + + #GFile to read + + + + a #GCancellable + + + + + + + + + + + + + + input #GFile + + + + the [I/O priority][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 #GFileInputStream or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + + + + + input #GFile + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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 valid #GFileOutputStream + or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + + + + + input #GFile + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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 #GFileOutputStream or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + a #GFileOutputStream or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + an optional [entity tag][gfile-etag] + 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 + + + + + + + + + + + + + + input #GFile + + + + an [entity tag][gfile-etag] for the current #GFile, + or %NULL to ignore + + + + %TRUE if a backup should be created + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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 #GFileOutputStream, or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + %TRUE if the file was deleted. %FALSE otherwise. + + + + + input #GFile + + + + optional #GCancellable object, + %NULL to ignore + + + + + + + + + + + + + + input #GFile + + + + the [I/O priority][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 file was deleted. %FALSE otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + %TRUE on successful trash, %FALSE otherwise. + + + + + #GFile to send to trash + + + + optional #GCancellable object, + %NULL to ignore + + + + + + + + + + + + + + input #GFile + + + + the [I/O priority][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 on successful trash, %FALSE otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + %TRUE on successful creation, %FALSE otherwise. + + + + + input #GFile + + + + optional #GCancellable object, + %NULL to ignore + + + + + + + + + + + + + + input #GFile + + + + the [I/O priority][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 on successful directory creation, %FALSE otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + %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 + + + + + + + + + + + + + + + + + + + + + + + + + + %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 + + + + + + + + + + + + + + input #GFile + + + + destination #GFile + + + + set of #GFileCopyFlags + + + + the [I/O priority][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 function + + + + + + + + + + a %TRUE on success, %FALSE on error. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + %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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + a #GFile or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + + + + + input #GFile + + + + flags affecting the operation + + + + optional #GCancellable object, + %NULL to ignore + + + + a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL + + + + the data to pass to callback function + + + + + + + + + + %TRUE if the operation finished successfully. + %FALSE otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + + + + + input #GFile + + + + flags affecting the operation + + + + optional #GCancellable object, + %NULL to ignore + + + + a #GAsyncReadyCallback to call + when the request is satisfied, or %NULL + + + + the data to pass to callback function + + + + + + + + + + %TRUE if the @file was ejected successfully. + %FALSE otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if successful. If an error has occurred, + this function will return %FALSE and set @error + appropriately if present. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref(). + + + + + #GFile to open + + + + a #GCancellable + + + + + + + + + + + + + + input #GFile + + + + the [I/O priority][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 #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + + + + + input #GFile + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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 #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + a #GFileIOStream or %NULL on error. + Free the returned object with g_object_unref(). + + + + + a #GFile + + + + an optional [entity tag][gfile-etag] + 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 + + + + + + + + + + + + + + input #GFile + + + + an [entity tag][gfile-etag] for the current #GFile, + or %NULL to ignore + + + + %TRUE if a backup should be created + + + + a set of #GFileCreateFlags + + + + the [I/O priority][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 #GFileIOStream, or %NULL on error. + Free the returned object with g_object_unref(). + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the operation finished successfully. %FALSE +otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + + + + + 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 + + + + + + + + + + %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. + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the operation finished successfully. + %FALSE otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the @file was ejected successfully. + %FALSE otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the operation finished successfully. %FALSE +otherwise. + + + + + input #GFile + + + + a #GAsyncResult + + + + + + + + + + %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 + + + + + + + + + + + + + + a #GFile + + + + #GFileMeasureFlags + + + + the [I/O priority][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 + + + + + + + + + + %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 + + + + + + + + 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 [GFileAttribute][gio-GFileAttribute] for more information on how +GIO handles file attributes. + +To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its +async variant). To obtain a #GFileInfo for a file input or output +stream, use g_file_input_stream_query_info() or +g_file_output_stream_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 g_file_set_attributes_from_info() +or g_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 g_file_info_set_size(). +You may call g_file_query_settable_attributes() and +g_file_query_writable_namespaces() to discover the settable attributes +of a particular file at runtime. + +#GFileAttributeMatcher 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][gio-GFileAttribute] 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 value of a attribute, formated as a string. +This escapes things as needed to make the string valid +UTF-8. + + + 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 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 an 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. + + + a string containing the file's content type. + + + + + 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. + + + a string containing the display name. + + + + + a #GFileInfo. + + + + + + Gets the edit name for a file. + + + a string containing the edit name. + + + + + a #GFileInfo. + + + + + + Gets the [entity tag][gfile-etag] for a given +#GFileInfo. See %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(). + + + a #GFileType for the given file. + + + + + a #GFileInfo. + + + + + + Gets the icon for a file. + + + #GIcon for the given @info. + + + + + a #GFileInfo. + + + + + + Checks if a file is a backup file. + + + %TRUE if file is a backup file, %FALSE otherwise. + + + + + a #GFileInfo. + + + + + + Checks if a file is hidden. + + + %TRUE if the file is a hidden file, %FALSE otherwise. + + + + + a #GFileInfo. + + + + + + Checks if a file is a 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. + + + modification time, or %NULL if unknown + + + + + a #GFileInfo. + + + + + + Gets the modification time of the current @info and sets it +in @result. + 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. + + + a string containing the file name. + + + + + a #GFileInfo. + + + + + + Gets the file's size. + + + a #goffset containing the file's size. + + + + + a #GFileInfo. + + + + + + Gets the value of the sort_order attribute from the #GFileInfo. +See %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. + + + #GIcon for the given @info. + + + + + a #GFileInfo. + + + + + + Gets the symlink target for a given #GFileInfo. + + + a string containing the symlink target. + + + + + a #GFileInfo. + + + + + + Checks if a file info structure has an attribute named @attribute. + + + %TRUE if @Ginfo 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 @Ginfo 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 @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. + + + + + + + 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. See [GContentType][gio-GContentType] + + + + + + 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 attribute in the file +info to the given date/time value. + + + + + + + a #GFileInfo. + + + + a #GDateTime. + + + + + + Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file +info to the given time value. + 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 #GSeekable, 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 g_seekable_tell(). To find out if a file input +stream supports seeking, use g_seekable_can_seek(). +To position a file input stream, use g_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][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 + + + + + + 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][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 + + + + + + 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][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 + + + + + + + + + + #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`. + + + 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 +g_file_monitor(), g_file_monitor_file(), or +g_file_monitor_directory(). + +To get informed about changes to the file or directory you are +monitoring, connect to the #GFileMonitor::changed signal. The +signal will be emitted in the +[thread-default main context][g-main-context-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][g-main-context-push-thread-default] of the +thread that the monitor was created in. + + + + + + + a #GFileMonitor. + + + + a #GFile. + + + + a #GFile. + + + + 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 + + + + + + + + + + + + + + + + + + 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 #GSeekable, 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 g_seekable_tell(). +To find out if a file output stream supports seeking, use +g_seekable_can_seek().To position a file output stream, use +g_seekable_seek(). To find out if a file output stream supports +truncating, use g_seekable_can_truncate(). To truncate a file output +stream, use g_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][gio-GIOScheduler] 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][gio-GIOScheduler] 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][gio-GIOScheduler] 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 completion for @initial_text from @completer. + + + a completed string, or %NULL if no completion exists. + This string is not owned by GIO, so remember to g_free() it + when finished. + + + + + 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. + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #GOutputStream. + + + + + a #GFilterOutputStream. + + + + + + Returns whether the base stream will be closed when @stream is +closed. + + + %TRUE if the base stream will be closed. + + + + + a #GFilterOutputStream. + + + + + + Sets whether the base stream will be closed when @stream is closed. + + + + + + + a #GFilterOutputStream. + + + + %TRUE to close the base stream. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + #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 is an opaque data structure and can only be accessed +using the following functions. + + + 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. + + + 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. + + + %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. + + + + the data to pass to 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 #GSocketConnection, which represents +a two-way network connection; and #GFileIOStream, which represents a +file handle opened in read-write mode. + +To do the actual reading and writing you need to get the substreams +with g_io_stream_get_input_stream() and g_io_stream_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 g_io_stream_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 #GIOStreams cannot be started while another operation on the +#GIOStream or its substreams is in progress. Specifically, an application can +read from the #GInputStream and write to the #GOutputStream 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 #GMainContext (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 #GIOStreams from other (worker) threads, and this +may be exposed to application code in the behaviour of wrapper streams, such +as #GBufferedInputStream or #GTlsConnection. 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 + + + + callback 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 + + + + callback 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 + + + + + + Asyncronously 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. + + + + user data passed to @callback. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + callback 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 #GThemedIcon), or the path to an icon (see #GLoadableIcon). + +To obtain a hash of a #GIcon, see g_icon_hash(). + +To check if two #GIcons are equal, see g_icon_equal(). + +For serializing a #GIcon, use g_icon_serialize() and +g_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: +#GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make +sense to have fast-paths for other cases (like handling #GdkPixbuf +directly, for example) but all compliant #GIcon implementations +outside of GIO must implement #GLoadableIcon. + +If your application or library provides one or more #GIcon +implementations you need to ensure that your new implementation also +implements #GLoadableIcon. Additionally, you must provide an +implementation of g_icon_serialize() that gives a result that is +understood by g_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() + + + + + + 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. + + + + + + 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. + + + + + 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. + + + + + + + + + + + + + + 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. + + + + + + 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. + + + + + 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 #guint containing a hash for the @icon, suitable for +use in a #GHashTable or similar data structure. + + + + + #gconstpointer to an icon object. + + + + + + + + + + %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. + + + + + pointer to the first #GIcon. + + + + pointer to the second #GIcon. + + + + + + + + + + An allocated NUL-terminated UTF8 string or +%NULL if @icon can't be serialized. Use g_free() to free. + + + + + a #GIcon. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GVariant, or %NULL when serialization fails. + + + + + a #GIcon + + + + + + + + #GInetAddress represents an IPv4 or IPv6 internet address. Use +g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to +look up the #GInetAddress for a hostname. Use +g_resolver_lookup_by_address() or +g_resolver_lookup_by_address_async() to look up the hostname for a +#GInetAddress. + +To actually connect to a remote host, you will need a +#GInetSocketAddress (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 + + + + + + Parses @string as an IP address and creates a new #GInetAddress. + + + 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 + + + + + + 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 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 + + + + + + + + + + + + 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(). + + + + + + + + + + + + + + + + + + + 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. Eg, "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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + An IPv4 or IPv6 socket address; that is, the combination of a +#GInetAddress and a port number. + + + + 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 `%`). + + + 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. + + + 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. + + + the scope id field + + + + + a %G_SOCKET_FAMILY_IPV6 #GInetAddress + + + + + + + + + The `sin6_flowinfo` field, for IPv6 addresses. + + + + + + + + + + + + + + + + + + + + + + + + + + #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 g_initable_init() or g_async_initable_init_async() +(the latter is only available if it also implements #GAsyncInitable). + +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. + +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 +g_initable_new() directly, or indirectly via a foo_thing_new() wrapper. +This will call g_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 implemention %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 [introduction][ginitable] 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 [introduction][ginitable] 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. + + + + + + + %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 has functions to read from a stream (g_input_stream_read()), +to close a stream (g_input_stream_close()) and to skip some content +(g_input_stream_skip()). + +To copy the content of an input stream to an output stream without +manually handling the reads and writes, use g_output_stream_splice(). + +See the documentation for #GIOStream 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][io-priority] of the request + + + + optional cancellable object + + + + callback 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][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 + + + + + + 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][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 + + + + + + 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][io-priority] of the request + + + + optional cancellable object + + + + callback 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 g_input_stream_read_all(). + +Call g_input_stream_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][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 + + + + + + Finishes an asynchronous stream read operation started with +g_input_stream_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][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 + + + + + + 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][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 + + + + + + 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][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 + + + + + + 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][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 + + + + + + + + + + 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][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 + + + + + + + + + + the size of the bytes skipped, or `-1` on error. + + + + + a #GInputStream. + + + + a #GAsyncResult. + + + + + + + + + + + + + + A #GInputStream. + + + + the [I/O priority][io-priority] of the request + + + + optional cancellable object + + + + callback 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 +#GObjects. 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 #GObject::notify signal). Taken together +with the #GListModel::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. +g_list_model_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: +g_list_model_get_n_items() returns the number of items in the list and +g_list_model_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 +g_list_model_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 faciliate 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][g-main-context-push-thread-default] +in effect at the time that the model was created. + + + 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 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_type() are of that type or a subtype, or 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 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_type() are of that type or a subtype, or 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 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 #GType of the items contained in @list. + + + + + a #GListModel + + + + + + + + + + the number of items in @list. + + + + + a #GListModel + + + + + + + + + + the object at @position. + + + + + a #GListModel + + + + the position of the item to fetch + + + + + + + + #GListStore is a simple implementation of #GListModel 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 + + + + + + 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. + + + + + + + + + + + Extends the #GIcon 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. + + + + + + + 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. + + + + + + + + + + + + + + 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 + + + + + + + + + + a #GInputStream to read the icon from. + + + + + a #GLoadableIcon. + + + + a #GAsyncResult. + + + + a location to store the type of the loaded + icon, %NULL to ignore. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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 +#GPollableInputStream. + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GMemoryOutputStream is a class for using arbitrary +memory chunks as output for GIO streaming output operations. + +As of GLib 2.34, #GMemoryOutputStream trivially implements +#GPollableOutputStream: 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 #GMenuModel. +You populate a #GMenu by adding #GMenuItem instances to it. + +There are some convenience functions to allow you to directly +add items (avoiding #GMenuItem) for the common cases. To add +a regular item, use g_menu_insert(). To add a section, use +g_menu_insert_section(). To add a submenu, use +g_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 encorporated 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 #GMenuModels. +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} + +![](menu-example.png) + +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][menu-model] 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 # {#menu-model} + +![](menu-model.png) + +Notice that the separators visible in the [example][menu-example] +appear nowhere in the [menu model][menu-model]. 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 [GActionGroup exporter][gio-GActionGroup-exporter] +and the [GMenuModel exporter][gio-GMenuModel-exporter] do for +#GActionGroup and #GMenuModel. The client-side counterparts to +make use of the exported information are #GDBusActionGroup and +#GDBusMenuModel. + +The API of #GMenuModel is very generic, with iterators for the +attributes and links of an item, see g_menu_model_iterate_item_attributes() +and g_menu_model_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, 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 occured 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 user-visible mounts. Note, when +porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume. + +#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. Might or +might not be related to a volume object. + +Unmounting a #GMount instance is an asynchronous operation. For +more information about asynchronous operations, see #GAsyncResult +and #GTask. To unmount a #GMount instance, first call +g_mount_unmount_with_operation() with (at least) the #GMount instance and a +#GAsyncReadyCallback. The callback will be fired when the +operation has resolved (either with success or failure), and a +#GAsyncResult structure will be passed to the callback. That +callback should then call g_mount_unmount_with_operation_finish() with the #GMount +and the #GAsyncResult data to see if the operation was completed +successfully. If an @error is present when g_mount_unmount_with_operation_finish() +is called, then it will be filled with any error information. + + + 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 an 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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + 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 an 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GFile. + The returned object should be unreffed with + g_object_unref() when no longer needed. + + + + + a #GMount. + + + + + + + + + + the name for the given @mount. + The returned string should be freed with g_free() + when no longer needed. + + + + + a #GMount. + + + + + + + + + + a #GIcon. + The returned object should be unreffed with + g_object_unref() when no longer needed. + + + + + a #GMount. + + + + + + + + + + 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. + + + + + + + + + + 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. + + + + + + + + + + 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. + + + + + + + + + + %TRUE if the @mount can be unmounted. + + + + + a #GMount. + + + + + + + + + + %TRUE if the @mount can be ejected. + + + + + a #GMount. + + + + + + + + + + + + + + a #GMount. + + + + flags affecting the operation + + + + optional #GCancellable object, %NULL to ignore. + + + + a #GAsyncReadyCallback, or %NULL. + + + + user data passed to @callback. + + + + + + + + + + %TRUE if the mount was successfully unmounted. %FALSE otherwise. + + + + + a #GMount. + + + + a #GAsyncResult. + + + + + + + + + + + + + + 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. + + + + + + + + + + %TRUE if the mount was successfully ejected. %FALSE otherwise. + + + + + a #GMount. + + + + a #GAsyncResult. + + + + + + + + + + + + + + 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. + + + + + + + + + + %TRUE if the mount was successfully remounted. %FALSE otherwise. + + + + + a #GMount. + + + + a #GAsyncResult. + + + + + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + %TRUE if the mount was successfully unmounted. %FALSE otherwise. + + + + + a #GMount. + + + + a #GAsyncResult. + + + + + + + + + + + + + + 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. + + + + + + + + + + %TRUE if the mount was successfully ejected. %FALSE otherwise. + + + + + a #GMount. + + + + a #GAsyncResult. + + + + + + + + + + a #GFile. + The returned object should be unreffed with + g_object_unref() when no longer needed. + + + + + a #GMount. + + + + + + + + + + Sorting key for @mount or %NULL if no such key is available. + + + + + A #GMount. + + + + + + + + + + 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 #GMount +objects – for example it is also used in g_drive_start() and +g_drive_stop(). + +Users should instantiate a subclass of this that implements all the +various callbacks to show the required dialogs, such as +#GtkMountOperation. 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. + +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 mesage 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][extending-gio]. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + An socket address of some unknown native type. + + + + 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 #GSocketConnectable 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + 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 + + + + + + + + + + + + + + + + + + + + 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. + +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. + + + + + + + + + + + + + + + + + + + + + + + %TRUE if @connectable is reachable, %FALSE if not. + + + + + a #GNetworkMonitor + + + + a #GSocketConnectable + + + + a #GCancellable, or %NULL + + + + + + + + + + + + + + a #GNetworkMonitor + + + + a #GSocketConnectable + + + + a #GCancellable, or %NULL + + + + a #GAsyncReadyCallback to call when the + request is satisfied + + + + the data to pass to callback function + + + + + + + + + + %TRUE if network is reachable, %FALSE if not. + + + + + a #GNetworkMonitor + + + + a #GAsyncResult + + + + + + + + Like #GNetworkAddress 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 #GSrvTarget for more information about SRV records, and see +#GSocketConnectable 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 + + + + + + Get's 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 #GApplication. + +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 g_application_send_notification(). + + 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 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. + +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 has functions to write to a stream (g_output_stream_write()), +to close a stream (g_output_stream_close()) and to flush pending writes +(g_output_stream_flush()). + +To copy the content of an input stream to an output stream without +manually handling the reads and writes, use g_output_stream_splice(). + +See the documentation for #GIOStream for details of thread safety of +streaming APIs. + +All of these functions have async variants too. + + + 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 + + + + callback 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. + + + + user data passed to @callback. + + + + + + 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. + + + + callback 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. + + + + callback 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 + + + + callback 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. + + + + user data passed to @callback. + + + + + + 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 + + + + callback 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. + + + + callback 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. + + + + callback 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 + + + + callback 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. + + + + callback 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. + + + + callback 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. + + + + user data passed to @callback. + + + + + + + + + + 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 + + + + callback 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. + + + + callback 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 proxy functionality. +See [Extending GIO][extending-gio]. + + + + + + + + + + + + + + + + + + + Extension point for proxy resolving functionality. +See [Extending GIO][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 #GSettings 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 #GInputStreams 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. + + + + 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. + + + 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. + + + %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 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. + + + 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. + + + %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 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. + + + + + + + %TRUE if @stream is pollable, %FALSE if not. + + + + + a #GPollableInputStream. + + + + + + + + + + %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. + + + + + + + + + + a new #GSource + + + + + a #GPollableInputStream. + + + + a #GCancellable, or %NULL + + + + + + + + + + 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 #GOutputStreams 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. + + + + 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. + + + 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. + + + %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 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. + + + %@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. + + + 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. + + + %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 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. + + + %@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. + + + + + + + %TRUE if @stream is pollable, %FALSE if not. + + + + + a #GPollableOutputStream. + + + + + + + + + + %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. + + + + + + + + + + a new #GSource + + + + + a #GPollableOutputStream. + + + + a #GCancellable, or %NULL + + + + + + + + + + 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 + + + + + + + + + + %@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. + + + + + + A #GPropertyAction is a way to get a #GAction with a state value +reflecting and controlling the value of a #GObject 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 #GParamSpec). + +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 #GEnumValue 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 #GVariant 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 #GAction corresponding to +the "visible-child-name" property of a #GtkStack 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. This is because the state of the combobox 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 if this value is actually stored in +#GSettings. In that case, the real source of the value is +#GSettings. If you want a #GAction to control a setting stored in +#GSettings, see g_settings_create_action() instead, and possibly +combine its use with g_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 +g_io_extension_point_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 + + + + + + + Support for proxied #GInetSocketAddress. + + + + 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 protocol being spoke to the destination host, or %NULL if +the #GProxyAddress doesn't know. + + + + + + + + + + The URI string that the proxy was constructed from (or %NULL +if the creator didn't specify this). + + + + + + + + + + + + + + Class structure for #GProxyAddress. + + + + + + + #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which +takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator +and wraps them in #GProxyAddress instances, using the given +#GProxyAddressEnumerator:proxy-resolver. + +This enumerator will be returned (for example, by +g_socket_connectable_enumerate()) as appropriate when a proxy is configured; +there should be no need to manually wrap a #GSocketAddressEnumerator instance +with one. + + + + + + The default port to use if #GProxyAddressEnumerator:uri does not +specify one. + + + + The proxy resolver to use. + + + + + + + + + + + + + + Class structure for #GProxyAddressEnumerator. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Provides an interface for handling proxy connection and payload. + + + The parent interface. + + + + + + + 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 + + + + + + + + + + + + + + a #GProxy + + + + a #GIOStream + + + + a #GProxyAddress + + + + a #GCancellable + + + + a #GAsyncReadyCallback + + + + callback data + + + + + + + + + + a #GIOStream. + + + + + a #GProxy + + + + a #GAsyncResult + + + + + + + + + + %TRUE if hostname resolution is supported. + + + + + a #GProxy + + + + + + + + #GProxyResolver provides synchronous and asynchronous network proxy +resolution. #GProxyResolver is used within #GSocketClient through +the method g_socket_connectable_proxy_enumerate(). + +Implementations of #GProxyResolver based on libproxy and GNOME settings can +be found in glib-networking. GIO comes with an implementation for use inside +Flatpak portals. + + + Gets the default #GProxyResolver for the system. + + + the default #GProxyResolver. + + + + + 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. + + + + + + + %TRUE if @resolver is supported. + + + + + a #GProxyResolver + + + + + + + + + + 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 + + + + + + + + + + + + + + a #GProxyResolver + + + + a URI representing the destination to connect to + + + + a #GCancellable, or %NULL + + + + callback to call after resolution completes + + + + data for @callback + + + + + + + + + + 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 #GActionGroup +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 #GActionGroup used to activate actions: +g_action_group_activate_action() and +g_action_group_change_action_state(). These variants allow a +"platform data" #GVariant to be specified: a dictionary providing +context for the action invocation (for example: timestamps, startup +notification IDs, etc). + +#GDBusActionGroup implements #GRemoteActionGroup. This provides a +mechanism to send platform data for action invocations over D-Bus. + +Additionally, g_dbus_connection_export_action_group() will check if +the exported #GActionGroup 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. + + + + + + + + + + + + + a #GDBusActionGroup + + + + the name of the action to activate + + + + the optional parameter to the activation + + + + the platform data to send + + + + + + + + + + + + + + a #GRemoteActionGroup + + + + the name of the action to change the state of + + + + the new requested value for the state + + + + the platform data to send + + + + + + + + #GResolver provides cancellable synchronous and asynchronous DNS +resolution, for hostnames (g_resolver_lookup_by_address(), +g_resolver_lookup_by_name() and their async variants) and SRV +(service) records (g_resolver_lookup_service()). + +#GNetworkAddress and #GNetworkService provide wrappers around +#GResolver functionality that also implement #GSocketConnectable, +making it easy to connect to a remote host/service. + + + 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 + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + 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 .ui files, splashscreen images, GMenu 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] program +provide a convenient and efficient alternative to this which has some nice properties. You +maintain the files as normal files, so its 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 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` which will use the gdk-pixbuf-pixdata command to convert +images to the GdkPixdata 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. + +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] 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 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] to compile the XML to a +binary bundle that you can load with g_resource_load(). However, its 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]. `get_resource()` returns +the generated #GResource object. The register and unregister functions +register the resource so its files can be accessed using +g_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 g_resources_open_stream() to stream the data or g_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 #GFile to access +the resource data. + +Some higher-level APIs, such as #GtkApplication, 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. + +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. + +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 path after +the slash 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 GResource 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 g_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 #GResource, or %NULL on error + + + + + A #GBytes + + + + + + 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 g_resources_lookup_data(). + + + + + + + A #GResource + + + + + + Unregisters the resource from the process-global set of resources. + + + + + + + A #GResource + + + + + + 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 g_strfreev(). + +If @path is invalid or does not exist in the #GResource, +%G_RESOURCE_ERROR_NOT_FOUND will be returned. + +@lookup_flags controls the behaviour of the lookup. + + + an array of constant strings + + + + + + + A #GResource + + + + A pathname inside the resource + + + + A #GResourceLookupFlags + + + + + + 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. + + + %TRUE if the file was found. %FALSE if there were errors + + + + + A #GResource + + + + A pathname inside the resource + + + + A #GResourceLookupFlags + + + + 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 + + + + + + Looks for a file at the specified @path in the resource and +returns a #GBytes 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 GBytes. + +For uncompressed resource files this is a pointer directly into +the resource bundle, which is typically in some readonly 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. + + + #GBytes or %NULL on error. + Free the returned object with g_bytes_unref() + + + + + A #GResource + + + + A pathname inside the resource + + + + A #GResourceLookupFlags + + + + + + Looks for a file at the specified @path in the resource and +returns a #GInputStream that lets you read the data. + +@lookup_flags controls the behaviour of the lookup. + + + #GInputStream or %NULL on error. + Free the returned object with g_object_unref() + + + + + A #GResource + + + + A pathname inside the resource + + + + A #GResourceLookupFlags + + + + + + Atomically increments the reference count of @resource by one. This +function is MT-safe and may be called from any thread. + + + The passed in #GResource + + + + + A #GResource + + + + + + 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 MT-safe and may be called from any +thread. + + + + + + + A #GResource + + + + + + Loads a binary resource bundle and creates a #GResource 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 g_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 g_mapped_file_new() will be +returned. + + + a new #GResource, 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 #GResource Error Quark. + + a #GQuark + + + + + + 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 +#GInputStream or #GOutputStream) 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() 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() 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 offset from the beginning of the buffer. + + + + + 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 +previouly 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 offset from the beginning of the buffer. + + + + + 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 +previouly 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. + + + + + + + the offset from the beginning of the buffer. + + + + + a #GSeekable. + + + + + + + + + + %TRUE if @seekable can be seeked. %FALSE otherwise. + + + + + a #GSeekable. + + + + + + + + + + %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. + + + + + + + + + + %TRUE if the stream can be truncated, %FALSE otherwise. + + + + + a #GSeekable. + + + + + + + + + + %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 +#GHashTable 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 g_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][gsettings-relocatable]', 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 #GVariant, and allows any #GVariantType 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: +|[ + <!-- 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 +#GVariants (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] +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://git.gnome.org/browse/glib/tree/gio/gschema.dtd) + +The [glib-compile-schemas][glib-compile-schemas] 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 #GVariant types, keys can have types that have +enumerated types. These can be described by a <choice>, +<enum> or <flags> element, as seen in the +[example][schema-enumerated]. The underlying type of such a key +is string, but you can use g_settings_get_enum(), g_settings_set_enum(), +g_settings_get_flags(), g_settings_set_flags() access the numeric values +corresponding to the string value of enum and flags keys. + +An example for default value: +|[ +<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: +|[ +<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] 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 GVariant 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`. + +## Binding + +A very convenient feature of GSettings lets you bind #GObject properties +directly to settings, using g_settings_bind(). Once a GObject property +has been bound to a setting, changes on either side are automatically +propagated to the other side. GSettings handles details like mapping +between GObject and GVariant 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 # {#gsettings-relocatable} + +A relocatable schema is one with no `path` attribute specified on its +<schema> element. By using g_settings_new_with_path(), a #GSettings object +can be instantiated for a relocatable schema, assigning a path to the +instance. Paths passed to g_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.: +|[ +<schema id="org.foo.MyApp" path="/org/foo/MyApp/"> + <child name="main" schema="org.foo.MyApp.Window"/> +</schema> +]| + +## Build system integration # {#gsettings-build-system} + +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@ +]| + +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 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 intltool XML rules with a +`.gschema.xml.in` template. + +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`. + + + Creates a new #GSettings object with the schema specified by +@schema_id. + +Signals on the newly created #GSettings object will be dispatched +via the thread-default #GMainContext in effect at the time of the +call to g_settings_new(). The new #GSettings will hold a reference +on the context. See g_main_context_push_thread_default(). + + + a new #GSettings object + + + + + the id of the schema + + + + + + Creates a new #GSettings 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 #GSettings object is a pure composition of +4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that +backend, and a #GMainContext to which signals are dispatched. + +This constructor therefore gives you full control over constructing +#GSettings 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 g_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 #GSettings object + + + + + a #GSettingsSchema + + + + a #GSettingsBackend + + + + the path to use + + + + + + Creates a new #GSettings object with the schema specified by +@schema_id and a given #GSettingsBackend. + +Creating a #GSettings 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 #GSettings object + + + + + the id of the schema + + + + the #GSettingsBackend to use + + + + + + Creates a new #GSettings object with the schema specified by +@schema_id and a given #GSettingsBackend and path. + +This is a mix of g_settings_new_with_backend() and +g_settings_new_with_path(). + + + a new #GSettings object + + + + + the id of the schema + + + + the #GSettingsBackend to use + + + + the path to use + + + + + + Creates a new #GSettings 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 #GSettings 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 #GSettings are handled asynchronously. For this +reason, it is very unlikely that the changes have it to disk by the +time g_settings_set() returns. + +This call will block until all of the writes have made it to the +backend. Since the mainloop 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 + + + + 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; +see g_settings_delay(). In the normal case settings are always +applied immediately. + + + + + + + a #GSettings instance + + + + + + 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 g_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 %G_SETTINGS_BIND_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 g_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. + + + + + + + a #GSettings object + + + + the key to bind + + + + a #GObject + + + + 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. + + + + + + + a #GSettings object + + + + the key to bind + + + + a #GObject + + + + 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 + + + + #GDestroyNotify function for @user_data + + + + + + 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. + + + + + + + a #GSettings object + + + + the key to bind + + + + a #GObject + + + + the name of a boolean property to bind + + + + whether to 'invert' the value + + + + + + Creates a #GAction corresponding to a given #GSettings 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 #GAction + + + + + a #GSettings + + + + the name of a key in @settings + + + + + + Changes the #GSettings object into 'delay-apply' mode. In this +mode, changes to @settings are not immediately propagated to the +backend, but kept locally until g_settings_apply() is called. + + + + + + + a #GSettings object + + + + + + Gets the value that is stored at @key in @settings. + +A convenience function that combines g_settings_get_value() with +g_variant_get(). + +It is a programmer error to give a @key that isn't contained in the +schema for @settings or for the #GVariantType of @format to mismatch +the type given in the schema. + + + + + + + a #GSettings object + + + + the key to get the value for + + + + a #GVariant format string + + + + arguments as per @format + + + + + + Gets the value that is stored at @key in @settings. + +A convenience variant of g_settings_get() for booleans. + +It is a programmer error to give a @key that isn't specified as +having a boolean type in the schema for @settings. + + + a boolean + + + + + a #GSettings 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. + +The schema for the child settings object must have been declared +in the schema of @settings using a <child> element. + + + a 'child' settings object + + + + + a #GSettings object + + + + the name of the child schema + + + + + + Gets the "default value" of a key. + +This is the value that would be read if g_settings_reset() were to be +called on the key. + +Note that this may be a different value than returned by +g_settings_schema_key_get_default_value() if the system administrator +has provided a default value. + +Comparing the return values of g_settings_get_default_value() and +g_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 + + + + + a #GSettings object + + + + the key to get the default value for + + + + + + Gets the value that is stored at @key in @settings. + +A convenience variant of g_settings_get() for doubles. + +It is a programmer error to give a @key that isn't specified as +having a 'double' type in the schema for @settings. + + + a double + + + + + a #GSettings 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 + + + + + a #GSettings 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 an 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 + + + + + a #GSettings object + + + + the key to get the value for + + + + + + Returns whether the #GSettings object has any unapplied +changes. This can only be the case if it is in 'delayed-apply' mode. + + + %TRUE if @settings has unapplied changes + + + + + a #GSettings object + + + + + + Gets the value that is stored at @key in @settings. + +A convenience variant of g_settings_get() for 32-bit integers. + +It is a programmer error to give a @key that isn't specified as +having a int32 type in the schema for @settings. + + + an integer + + + + + a #GSettings object + + + + the key to get the value for + + + + + + Gets the value that is stored at @key in @settings. + +A convenience variant of g_settings_get() for 64-bit integers. + +It is a programmer error to give a @key that isn't specified as +having a int64 type in the schema for @settings. + + + a 64-bit integer + + + + + a #GSettings 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 + + + + + a #GSettings 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 g_settings_schema_key_get_range() instead. + + + + + + + a #GSettings + + + + the key to query the range of + + + + + + Gets the value that is stored at @key in @settings. + +A convenience variant of g_settings_get() for strings. + +It is a programmer error to give a @key that isn't specified as +having a string type in the schema for @settings. + + + a newly-allocated string + + + + + a #GSettings object + + + + the key to get the value for + + + + + + A convenience variant of g_settings_get() for string arrays. + +It is a programmer error to give a @key that isn't specified as +having an array of strings type in the schema for @settings. + + + a +newly-allocated, %NULL-terminated array of strings, the value that +is stored at @key in @settings. + + + + + + + a #GSettings object + + + + the key to get the value for + + + + + + Gets the value that is stored at @key in @settings. + +A convenience variant of g_settings_get() for 32-bit unsigned +integers. + +It is a programmer error to give a @key that isn't specified as +having a uint32 type in the schema for @settings. + + + an unsigned integer + + + + + a #GSettings object + + + + the key to get the value for + + + + + + Gets the value that is stored at @key in @settings. + +A convenience variant of g_settings_get() for 64-bit unsigned +integers. + +It is a programmer error to give a @key that isn't specified as +having a uint64 type in the schema for @settings. + + + a 64-bit unsigned integer + + + + + a #GSettings 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 g_settings_reset() this function should always return +%NULL (assuming something is not wrong with the system +configuration). + +It is possible that g_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 + + + + + a #GSettings 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 #GVariant + + + + + a #GSettings object + + + + the key to get the value for + + + + + + Finds out if a key can be written or not + + + %TRUE if the key @name is writable + + + + + a #GSettings 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 g_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 g_strfreev() when you are done +with it. + + + a list of the children on + @settings, in no defined order + + + + + + + a #GSettings 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 g_strfreev() when you are done +with it. + Use g_settings_schema_list_keys instead(). + + + a list of the keys on + @settings, in no defined order + + + + + + + a #GSettings object + + + + + + Checks if the given @value is of the correct type and within the +permitted range for @key. + Use g_settings_schema_key_range_check() instead. + + + %TRUE if @value is valid for @key + + + + + a #GSettings + + + + 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. + + + + + + + a #GSettings object + + + + the name of a key + + + + + + Reverts all non-applied changes to the settings. This function +does nothing unless @settings is in 'delay-apply' mode; see +g_settings_delay(). In the normal case settings are always applied +immediately. + +Change notifications will be emitted for affected keys. + + + + + + + a #GSettings instance + + + + + + Sets @key in @settings to @value. + +A convenience function that combines g_settings_set_value() with +g_variant_new(). + +It is a programmer error to give a @key that isn't contained in the +schema for @settings or for the #GVariantType of @format to mismatch +the type given in the schema. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + a #GVariant format string + + + + arguments as per @format + + + + + + Sets @key in @settings to @value. + +A convenience variant of g_settings_set() for booleans. + +It is a programmer error to give a @key that isn't specified as +having a boolean type in the schema for @settings. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + the value to set it to + + + + + + Sets @key in @settings to @value. + +A convenience variant of g_settings_set() for doubles. + +It is a programmer error to give a @key that isn't specified as +having a 'double' type in the schema for @settings. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + 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 +g_settings_get_string() will return the 'nick' associated with +@value. + + + %TRUE, if the set succeeds + + + + + a #GSettings object + + + + a key, within @settings + + + + 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 +g_settings_get_strv() will return an array of 'nicks'; one for each +bit in @value. + + + %TRUE, if the set succeeds + + + + + a #GSettings object + + + + a key, within @settings + + + + a flags value + + + + + + Sets @key in @settings to @value. + +A convenience variant of g_settings_set() for 32-bit integers. + +It is a programmer error to give a @key that isn't specified as +having a int32 type in the schema for @settings. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + the value to set it to + + + + + + Sets @key in @settings to @value. + +A convenience variant of g_settings_set() for 64-bit integers. + +It is a programmer error to give a @key that isn't specified as +having a int64 type in the schema for @settings. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + the value to set it to + + + + + + Sets @key in @settings to @value. + +A convenience variant of g_settings_set() for strings. + +It is a programmer error to give a @key that isn't specified as +having a string type in the schema for @settings. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + the value to set it to + + + + + + Sets @key in @settings to @value. + +A convenience variant of g_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 array of strings type in the schema for @settings. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + the value to set it to, or %NULL + + + + + + + + Sets @key in @settings to @value. + +A convenience variant of g_settings_set() for 32-bit unsigned +integers. + +It is a programmer error to give a @key that isn't specified as +having a uint32 type in the schema for @settings. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + the value to set it to + + + + + + Sets @key in @settings to @value. + +A convenience variant of g_settings_set() for 64-bit unsigned +integers. + +It is a programmer error to give a @key that isn't specified as +having a uint64 type in the schema for @settings. + + + %TRUE if setting the key succeeded, + %FALSE if the key was not writable + + + + + a #GSettings object + + + + the name of the key to set + + + + 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 + + + + + a #GSettings object + + + + the name of the key to set + + + + a #GVariant of the correct type + + + + + + The name of the context that the settings are stored in. + + + + Whether the #GSettings object is in 'delay-apply' mode. See +g_settings_delay() for details. + + + + If this property is %TRUE, the #GSettings object has outstanding +changes that will be applied when g_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 #GSettings object. + +The type of this property is *not* #GSettingsSchema. +#GSettingsSchema 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 +'settings-schema' property if you wish to pass in a +#GSettingsSchema. + Use the 'schema-id' property instead. In a future +version, this property may instead refer to a #GSettingsSchema. + + + + The name of the schema that describes the types of keys +for this #GSettings object. + + + + The #GSettingsSchema describing the types of keys for this +#GSettings object. + +Ideally, this property would be called 'schema'. #GSettingsSchema +has only existed since version 2.32, however, and before then the +'schema' property was used to refer to the ID of the schema rather +than the schema itself. Take care. + + + + + + + + + + The "change-event" signal is 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 "changed" signal. +For most use cases it is more appropriate to use the "changed" signal. + +In the event that the change event applies to one or more specified +keys, @keys will be an array of #GQuark of length @n_keys. In the +event that the change event applies to the #GSettings 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 "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. + + + + + + an array of #GQuarks for the changed keys, or %NULL + + + + + + the length of the @keys array, or 0 + + + + + + The "changed" signal is emitted when a key has potentially changed. +You should call one of the g_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 + + + + + + The "writable-change-event" signal is 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 +"writable-changed" signal. For most use cases it is more +appropriate to use the "writable-changed" signal. + +In the event that the writability change applies only to a single +key, @key will be set to the #GQuark 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 "writable-changed" +and "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 + + + + + + The "writable-changed" signal is emitted when the writability of a +key has potentially changed. You should call +g_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 #GSettings, 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 #GTree. +These trees always have strings as keys and #GVariant as values. +g_settings_backend_create_tree() is a convenience function to create +suitable trees. + +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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 contatenation 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #GObject property when the setting changes. + It is an error to use this flag if the property is not writable. + + + Update the setting when the #GObject 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 #G_SETTINGS_BIND_GET, set the #GObject property + value initially from the setting, but do not listen for changes of the setting + + + When passed to g_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 g_settings_bind_with_mapping(). + + + + The type for the function that is used to convert from #GSettings 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 + + + + the #GVariant + + + + 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 #GVariant for storing it in #GSettings. + + + a new #GVariant holding the data from @value, + or %NULL in case of an error + + + + + a #GValue containing the property value to map + + + + the #GVariantType to create + + + + 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 #GSettings 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 + + + + + the #GVariant to map, or %NULL + + + + the result of the mapping + + + + the user data that was passed to +g_settings_get_mapped() + + + + + + + + + The #GSettingsSchemaSource 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. + +#GSettingsSchemaSource 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: + +|[<!-- language="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: + +|[<!-- language="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 +threfore 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 of the correct type and 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 #GAction +interface. This is the easiest way to create an action for purposes of +adding it to a #GSimpleActionGroup. + +See also #GtkAction. + + + 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 #GAction objects, +implementing the #GActionGroup and #GActionMap 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 +#GTask, which provides a simpler API. + +#GSimpleAsyncResult implements #GAsyncResult. + +GSimpleAsyncResult handles #GAsyncReadyCallbacks, 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 #GAsyncResult'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. + +GSimpleAsyncResults 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 g_simple_async_result_new(). +If the result needs to be created for a #GError, use +g_simple_async_result_new_from_error() or +g_simple_async_result_new_take_error(). If a #GError is not available +(e.g. the asynchronous operation's doesn't take a #GError argument), +but the result still needs to be created for an error condition, use +g_simple_async_result_new_error() (or g_simple_async_result_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 +g_simple_async_result_propagate_error(). + +An asynchronous operation can be made to ignore a cancellation event by +calling g_simple_async_result_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, #GMainLoop, +or it can use #GThreads. +g_simple_async_result_complete() will finish an I/O task directly +from the point where it is called. g_simple_async_result_complete_in_idle() +will finish it from an idle handler in the +[thread-default main context][g-main-context-push-thread-default] +where the #GSimpleAsyncResult was created. +g_simple_async_result_run_in_thread() will run the job in a +separate thread and then use +g_simple_async_result_complete_in_idle() to deliver the result. + +To set the results of an asynchronous function, +g_simple_async_result_set_op_res_gpointer(), +g_simple_async_result_set_op_res_gboolean(), and +g_simple_async_result_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, +g_simple_async_result_get_op_res_gpointer(), +g_simple_async_result_get_op_res_gboolean(), and +g_simple_async_result_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 +#GAsyncResult. A typical implementation of an asynchronous operation +using GSimpleAsyncResult looks something like this: + +|[<!-- language="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][g-main-context-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 #GIOStream from an arbitrary #GInputStream and +#GOutputStream. This allows any pair of input and output streams to be used +with #GIOStream methods. + +This is useful when you obtained a #GInputStream and a #GOutputStream +by other means, for instance creating them with platform specific methods as +g_unix_input_stream_new() or g_win32_input_stream_new(), and you want +to take advantage of the methods provided by #GIOStream. + + Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. +See also #GIOStream. + + + a new #GSimpleIOStream instance. + + + + + a #GInputStream. + + + + a #GOutputStream. + + + + + + + + + + + + + #GSimplePermission is a trivial implementation of #GPermission that +represents a permission that is either always or never allowed. The +value is given at construction and doesn't change. + +Calling request or release 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 #GProxyResolver 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 g_socket_client_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 #GSocketClient, +#GSocketService and #GSocketConnection. However there may be cases where +direct use of #GSocket is useful. + +#GSocket implements the #GInitable interface, so if it is manually constructed +by e.g. g_object_new() you must call g_initable_init() and check the +results before using the object. This is done automatically in +g_socket_new() and g_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 g_socket_condition_check(), +or g_socket_condition_wait(). You can also use g_socket_create_source() and +attach it to a #GMainContext 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. + +#GSockets 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. + + + + + 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 + +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>][gio-gnetworking.h] +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 + + + + + + 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.) + +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>][gio-gnetworking.h] +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 the socket should allow sending to broadcast addresses. + + + + + + + + + + + + + + + + + + + Whether outgoing multicast packets loop back to the local host. + + + + Time-to-live out outgoing multicast packets + + + + + + + + + + The timeout in seconds on socket I/O + + + + Time-to-live for outgoing unicast packets + + + + + + + + + + + + + + #GSocketAddress is the equivalent of struct sockaddr in the BSD +sockets API. This is an abstract class; use #GInetSocketAddress +for internet sockets, or #GUnixSocketAddress 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 + + + + + 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 + + + + + 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 socket family type of @address + + + + + a #GSocketAddress + + + + + + + + + + the size of the native struct sockaddr that + @address represents + + + + + 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 #GSocketAddress +instances. It is returned by enumeration functions such as +g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator +to list each #GSocketAddress which could be used to connect to that +#GSocketConnectable. + +Enumeration is typically a blocking operation, so the asynchronous methods +g_socket_address_enumerator_next_async() and +g_socket_address_enumerator_next_finish() should be used where possible. + +Each #GSocketAddressEnumerator can only be enumerated once. Once +g_socket_address_enumerator_next() has returned %NULL (and no error), 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. + + + + + + + + + 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. + + + + + + + + + + + + + + a #GSocketAddressEnumerator + + + + optional #GCancellable object, %NULL to ignore. + + + + a #GAsyncReadyCallback to call when the request + is satisfied + + + + the data to pass to callback function + + + + + + + + + + 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 #GSocketConnection +subclass on success. + +The type of the #GSocketConnection 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 #GTcpConnection. + +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(). + +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. + + + 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. + + + + + + + a #GSocketClient. + + + + the validation flags + + + + + + + + + + + + + + + + + + The proxy resolver to use + + + + + + + + + + + + + + + + + + + + + + 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, that 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 +g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator +to try out each socket address in turn until one succeeds, as shown +in the sample code below. + +|[<!-- language="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. + + + + + + + a new #GSocketAddressEnumerator. + + + + + a #GSocketConnectable + + + + + + + + + + a new #GSocketAddressEnumerator. + + + + + a #GSocketConnectable + + + + + + + + + + the formatted string + + + + + a #GSocketConnectable + + + + + + + + #GSocketConnection is a #GIOStream for a connected socket. They +can be created either by #GSocketClient when connecting to a host, +or by #GSocketListener 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 #GTcpConnection. + +Choosing what type of object to construct is done with the socket +connection factory, and it is possible for 3rd parties to register +custom socket connection types for specific combination of socket +family/type/protocol using g_socket_connection_factory_register_type(). + +To close a #GSocketConnection, use g_io_stream_close(). Closing both +substreams of the #GIOStream separately will not close the underlying +#GSocket. + + + 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. + +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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A #GSocketControlMessage is a special-purpose utility message that +can be sent to or received from a #GSocket. 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 g_socket_send_message() and received +with g_socket_receive_message(). + +To extend the set of control message 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 GType typesystem before calling +g_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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + The number of bytes required. + + + + + a #GSocketControlMessage + + + + + + + + + + an integer describing the level + + + + + a #GSocketControlMessage + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GSocketControlMessage + + + + A buffer to write data to + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 g_socket_listener_add_address() +and g_socket_listener_add_inet_port(). These will be listened on until +g_socket_listener_close() is called. Dropping your final reference to the +#GSocketListener will not cause g_socket_listener_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 #GSocketService +and #GThreadedSocketService 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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_socket() +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. + +@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. + +@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. + +@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 + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #GSocketService::incoming +signal is emitted. + +A #GSocketService is a subclass of #GSocketListener and you need +to add the addresses you want to accept connections on with the +#GSocketListener APIs. + +There are two options for implementing a network service based on +#GSocketService. The first is to create the service using +g_socket_service_new() and to connect to the #GSocketService::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 #GThreadedSocketService. + +The socket service runs on the main loop of the +[thread-default context][g-main-context-push-thread-default-context] +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. + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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). + + + + 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 g_resolver_lookup_service() or +g_resolver_lookup_service_async() to find the #GSrvTargets +for a given service. However, if you are simply planning to connect +to the remote service, you can use #GNetworkService's +#GSocketConnectable 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. + + + + + + + + + + + + + + + + + + Finalized a GResource initialized by g_static_resource_init(). + +This is normally used by code generated by +[glib-compile-resources][glib-compile-resources] +and is not typically used by other code. + + + + + + + pointer to a static #GStaticResource + + + + + + Gets the GResource that was registered by a call to g_static_resource_init(). + +This is normally used by code generated by +[glib-compile-resources][glib-compile-resources] +and is not typically used by other code. + + + a #GResource + + + + + pointer to a static #GStaticResource + + + + + + Initializes a GResource from static data using a +GStaticResource. + +This is normally used by code generated by +[glib-compile-resources][glib-compile-resources] +and is not typically used by other code. + + + + + + + pointer to a static #GStaticResource + + + + + + + #GSubprocess allows the creation of and interaction with child +processes. + +Processes can be communicated with using standard GIO-style APIs (ie: +#GInputStream, #GOutputStream). 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 +g_output_stream_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 g_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. g_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. + +#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 g_subprocess_new(). The +#GSubprocessLauncher 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 +g_subprocess_new(), followed by g_subprocess_wait_async() or +g_subprocess_wait(). After the process exits, the status can be +checked using functions such as g_subprocess_get_if_exited() (which +are similar to the familiar WIFEXITED-style POSIX macros). + + + 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_exit_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. + + + 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. + + + 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. + + + 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_exit_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_exit_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 + + + + + + + + + + + + + + + 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). + + + + 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 #GSubprocess 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 + + + + + + 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 #GSubprocess + + + + 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 #GSubprocess + + + + 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 #GSubprocess + + + + + 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 + + + + + + + + + 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 #GSubprocess + + + + 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 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 #GSubprocess + + + + the environment variable to unset, + must not contain '=' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Extension point for TLS functionality via #GTlsBackend. +See [Extending GIO][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 #GAsyncResult, to +manage data during an asynchronous operation. You call +g_task_new() in the "start" method, followed by +g_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 +g_task_return_pointer() or g_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][g-main-context-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 #GAsyncResult), and you can +use g_task_propagate_pointer() or the like to extract the +return value. + +Here is an example for using GTask as a GAsyncResult: +|[<!-- language="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. g_task_get_cancellable(), g_task_get_context(), +and g_task_get_priority() allow you to get back the task's +#GCancellable, #GMainContext, and [I/O priority][io-priority] +when starting a new subtask, so you don't have to keep track +of them yourself. g_task_attach_source() simplifies the case +of waiting for a source to fire (automatically using the correct +#GMainContext and priority). + +Here is an example for chained asynchronous operations: + |[<!-- language="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 g_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][g-main-context-push-thread-default] +where the #GTask was created. + +Running a task in a thread: + |[<!-- language="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, g_task_run_in_thread() and g_task_run_in_thread_sync() +can be used to turn an uncancellable operation into a +cancellable one. If you call g_task_set_return_on_cancel(), +passing %TRUE, then if the task's #GCancellable 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: + |[<!-- language="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 GSimpleAsyncResult + +#GTask's API attempts to be simpler than #GSimpleAsyncResult's +in several ways: +- You can save task-specific data with g_task_set_task_data(), and + retrieve it later with g_task_get_task_data(). This replaces the + abuse of g_simple_async_result_set_op_res_gpointer() for the same + purpose with #GSimpleAsyncResult. +- In addition to the task data, #GTask also keeps track of the + [priority][io-priority], #GCancellable, and + #GMainContext 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. +- g_task_return_error_if_cancelled() provides simplified + handling for cancellation. In addition, cancellation + overrides any other #GTask return value by default, like + #GSimpleAsyncResult does when + g_simple_async_result_set_check_cancellable() is called. + (You can use g_task_set_check_cancellable() to turn off that + behavior.) On the other hand, g_task_run_in_thread() + guarantees that it will always run your + `task_func`, even if the task's #GCancellable + is already cancelled before the task gets a chance to run; + you can start your `task_func` with a + g_task_return_error_if_cancelled() check if you need the + old behavior. +- The "return" methods (eg, g_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 #GMainContext, or delayed + until the next iteration of the current #GMainContext.) +- The "finish" functions for #GTask based operations are generally + much simpler than #GSimpleAsyncResult ones, normally consisting + of only a single call to g_task_propagate_pointer() or the like. + Since g_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 #GSimpleAsyncResult, it was common to call + g_simple_async_result_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 + g_async_result_legacy_propagate_error() to do old-style + #GSimpleAsyncResult error-returning behavior, and + g_async_result_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 g_input_stream_read_async()). + + + + Creates a #GTask acting on @source_object, which will eventually be +used to invoke @callback in the current +[thread-default main context][g-main-context-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][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. + +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][g-main-context-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 + + + + + + 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 g_task_return_new_error(). + + + + + + + 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 @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. + + + + + + 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, 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 + + + + + + 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][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 +uninterruptable 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. + + + + + + + the #GTask + + + + an opaque pointer indicating the source of this task + + + + + + 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. + +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 #GSocketConnection 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 + + + + + + + + + + + + + + + + + + + + + + + + + A #GTcpWrapperConnection can be used to wrap a #GIOStream that is +based on a #GSocket, but which is not actually a +#GSocketConnection. This is used by #GSocketClient so that it can +always return a #GSocketConnection, even when the connection it has +actually created is not directly a #GSocketConnection. + + + Wraps @base_io_stream and @socket together as a #GSocketConnection. + + + the new #GSocketConnection. + + + + + the #GIOStream to wrap + + + + the #GSocket associated with @base_io_stream + + + + + + Get's @conn's base #GIOStream + + + @conn's base #GIOStream + + + + + a #GTcpWrapperConnection + + + + + + + + + + + + + + + + + + + + + + + + + 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(). +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://git.gnome.org/browse/glib/tree/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 GSettings 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 #GIcon 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 gtk_icon_theme_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 +}; +]| + + + + + + + + A #GThreadedSocketService is a simple subclass of #GSocketService +that handles incoming connections by creating a worker thread and +dispatching the connection to it by emitting the +#GThreadedSocketService::run signal in the new thread. + +The signal handler may perform blocking IO 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 #GSocketService from accepting +new connections when all threads are busy. + +As with #GSocketService, you may connect to #GThreadedSocketService::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 ::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. + + + Gets the default #GTlsBackend for the system. + + + a #GTlsBackend + + + + + 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. + + + + + + + whether or not TLS is supported + + + + + the #GTlsBackend + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the default database, which should be + unreffed when done. + + + + + the #GTlsBackend + + + + + + + + + + whether DTLS is supported + + + + + the #GTlsBackend + + + + + + + + + + + + + + + + + + + + + + + + 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 +#GTlsServerConnection). + + + Creates a #GTlsCertificate from the PEM-encoded data in @file. The +returned certificate will be the first certificate found in @file. As +of GLib 2.44, if @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 @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 a PEM-encoded certificate to import + + + + + + 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 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 @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. + +(All other #GTlsCertificateFlags values will always be set or unset +as appropriate.) + + + the appropriate #GTlsCertificateFlags + + + + + a #GTlsCertificate + + + + the expected peer identity + + + + the certificate of a trusted authority + + + + + + 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 + + + + + + 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 @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. + +(All other #GTlsCertificateFlags values will always be set or unset +as appropriate.) + + + 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. + + + + 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. + + + + The DER (binary) encoded representation of the certificate's +private key, in either PKCS#1 format or unencrypted PKCS#8 +format. This property (or the #GTlsCertificate:private-key-pem +property) can be set when constructing a key (eg, from a file), +but cannot be read. + +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. + + + + + + The PEM (ASCII) encoded representation of the certificate's +private key in either PKCS#1 format ("`BEGIN RSA PRIVATE +KEY`") or unencrypted PKCS#8 format ("`BEGIN +PRIVATE KEY`"). This property (or the +#GTlsCertificate:private-key property) can be set when +constructing a key (eg, from a file), but cannot be read. + +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. + + + + + + + + + + + + + + + + + + + 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 set which validation steps to perform (eg, with +g_tls_client_connection_set_validation_flags()), or to describe why +a particular certificate was rejected (eg, in +#GTlsConnection::accept-certificate). + + 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 + + + + #GTlsClientConnection is the client-side subclass of +#GTlsConnection, 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 + + + + + + Copies session state from one connection to another. 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 @conn should not have +completed a handshake. + + + + + + + a #GTlsClientConnection + + + + a #GTlsClientConnection + + + + + + Copies session state from one connection to another. 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 @conn should not have +completed a handshake. + + + + + + + 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 + + + + + + Gets whether @conn will force the lowest-supported TLS protocol +version rather than attempt to negotiate the highest mutually- +supported version of TLS; see g_tls_client_connection_set_use_ssl3(). + SSL 3.0 is insecure, and this function does not +actually indicate whether it is enabled. + + + whether @conn will use the lowest-supported TLS protocol version + + + + + the #GTlsClientConnection + + + + + + Gets @conn's validation flags + + + 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 2.42.1, if @use_ssl3 is %TRUE, this forces @conn to use the +lowest-supported TLS protocol version rather than trying to properly +negotiate the highest mutually-supported protocol version with the +peer. Be aware that SSL 3.0 is generally disabled by the +#GTlsBackend, so the lowest-supported protocol version is probably +not SSL 3.0. + +Since 2.58, this may additionally cause an RFC 7507 fallback SCSV to +be sent to the server, causing modern TLS servers to immediately +terminate the connection. You should generally only use this function +if you need to connect to broken servers that exhibit TLS protocol +version intolerance, and when an initial attempt to connect to a +server normally has already failed. + SSL 3.0 is insecure, and this function does not +generally enable or disable it, despite its name. + + + + + + + the #GTlsClientConnection + + + + whether to use the lowest-supported protocol version + + + + + + 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. + + + + + + + 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. + + + + If %TRUE, forces the connection to use a fallback version of TLS +or SSL, rather than trying to negotiate the best version of TLS +to use. See g_tls_client_connection_set_use_ssl3(). + SSL 3.0 is insecure, and this property does not +generally enable or disable it, despite its name. + + + + What steps to perform when validating a certificate received from +a server. Server certificates that fail to validate in all of the +ways indicated here will be rejected unless the application +overrides the default via #GTlsConnection::accept-certificate. + + + + + vtable for a #GTlsClientConnection implementation. + + + The parent interface. + + + + + + + + + + + a #GTlsClientConnection + + + + a #GTlsClientConnection + + + + + + + + #GTlsConnection is the base TLS connection class type, which wraps +a #GIOStream and provides TLS encryption on top of it. Its +subclasses, #GTlsClientConnection and #GTlsServerConnection, +implement client-side and server-side TLS, respectively. + +For DTLS (Datagram TLS) support, see #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 (or after sending a "STARTTLS"-type command) and may +need to rehandshake later if the server requests it, +#GTlsConnection will handle this for you automatically when you try +to send or receive data on the connection. However, you can call +g_tls_connection_handshake() manually if you want to know for sure +whether the initial handshake succeeded or failed (as opposed to +just immediately trying to write to @conn's output stream, in which +case if it fails, it may not be possible to tell if it failed +before or after completing the handshake). + +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. + +If TLS 1.2 or older is in use, you may call +g_tls_connection_handshake() after the initial handshake to +rehandshake; however, this usage is deprecated because rehandshaking +is no longer part of the TLS protocol in TLS 1.3. Accordingly, the +behavior of calling this function after the initial handshake is now +undefined, except it is guaranteed to be reasonable and +nondestructive so as to preserve compatibility with code written for +older versions of GLib. + +#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][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 + + + + + + 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. +(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. (It is not set +during the emission of #GTlsConnection::accept-certificate.) + + + @conn's peer's certificate errors + + + + + 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. + + + @conn's rehandshaking mode + + + + + 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) and may +need to rehandshake later if the server requests it, +#GTlsConnection will handle this for you automatically when you try +to send or receive data on the connection. However, you can call +g_tls_connection_handshake() manually if you want to know for sure +whether the initial handshake succeeded or failed (as opposed to +just immediately trying to write to @conn's output stream, in which +case if it fails, it may not be possible to tell if it failed +before or after completing the handshake). + +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. + +If TLS 1.2 or older is in use, you may call +g_tls_connection_handshake() after the initial handshake to +rehandshake; however, this usage is deprecated because rehandshaking +is no longer part of the TLS protocol in TLS 1.3. Accordingly, the +behavior of calling this function after the initial handshake is now +undefined, except it is guaranteed to be reasonable and +nondestructive so as to preserve compatibility with code written for +older versions of GLib. + +#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][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). + + + + + + + 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 + + + + + + Sets how @conn behaves with respect to rehandshaking requests, when +TLS 1.2 or older is in use. + +%G_TLS_REHANDSHAKE_NEVER means that it will never agree to +rehandshake after the initial handshake is complete. (For a client, +this means it will refuse rehandshake requests from the server, and +for a server, this means it will close the connection with an error +if the client attempts to rehandshake.) + +%G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a +rehandshake only if the other end of the connection supports the +TLS `renegotiation_info` extension. This is the default behavior, +but means that rehandshaking will not work against older +implementations that do not support that extension. + +%G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow +rehandshaking even without the `renegotiation_info` extension. On +the server side in particular, this is not recommended, since it +leaves the server open to certain attacks. However, this mode is +necessary if you need to allow renegotiation with older client +software. + 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 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(). + + + + 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 and the certificate has been accepted. 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-and-ignored 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. + + + + The rehandshaking mode. See +g_tls_connection_set_rehandshake_mode(). + + + + 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. + +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + success or failure + + + + + a #GTlsConnection + + + + a #GCancellable, or %NULL + + + + + + + + + + + + + + a #GTlsConnection + + + + the [I/O priority][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 + + + + + + + + + + %TRUE on success, %FALSE on failure, in which +case @error will be set. + + + + + a #GTlsConnection + + + + a #GAsyncResult. + + + + + + + + + + + + + + + + #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 #GTlsConnection. + + + 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. + + + 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 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 after looking up and +adding any missing certificates to the chain. + +@chain is a chain of #GTlsCertificate objects each pointing to the next +certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially +consist of one or more certificates. After the verification process is +complete, @chain may be modified by adding missing certificates, or removing +extra certificates. If a certificate anchor was found, then it is added to +the @chain. + +@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 check for pinned certificates (trust exceptions) +in the database. These will 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 +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. + +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. + + + 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 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 after looking up and +adding any missing certificates to the chain. + +@chain is a chain of #GTlsCertificate objects each pointing to the next +certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially +consist of one or more certificates. After the verification process is +complete, @chain may be modified by adding missing certificates, or removing +extra certificates. If a certificate anchor was found, then it is added to +the @chain. + +@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 check for pinned certificates (trust exceptions) +in the database. These will 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 +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. + +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. + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + the appropriate #GTlsCertificateFlags which represents the +result of verification. + + + + + a #GTlsDatabase + + + + a #GAsyncResult. + + + + + + + + + + a newly allocated string containing the +handle. + + + + + a #GTlsDatabase + + + + certificate for which to create a 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + a newly allocated #GTlsCertificate object. +Use g_object_unref() to release the certificate. + + + + + a #GTlsDatabase + + + + a #GAsyncResult. + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + a newly allocated issuer #GTlsCertificate, +or %NULL. Use g_object_unref() to release the certificate. + + + + + a #GTlsDatabase + + + + a #GAsyncResult. + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + 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 + + + Gets the TLS error quark. + + a #GQuark. + + + + + + #GTlsFileDatabase is implemented by #GTlsDatabase 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 +g_tls_connection_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 +g_tls_interaction_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 an 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 an 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. + + + + + + + + + The status of the ask password interaction. + + + + + a #GTlsInteraction object + + + + a #GTlsPassword object + + + + an optional #GCancellable cancellation object + + + + + + + + + + + + + + a #GTlsInteraction object + + + + a #GTlsPassword object + + + + an optional #GCancellable cancellation object + + + + will be called when the interaction completes + + + + data to pass to the @callback + + + + + + + + + + The status of the ask password interaction. + + + + + a #GTlsInteraction object + + + + the result passed to the callback + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + 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. + + + + Holds a password used in TLS. + + + Create a new #GTlsPassword object. + + + The newly allocated password object + + + + + the password flags + + + + description of what the password is for + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + Class structure for #GTlsPassword. + + + + + + + + + The password value (owned by the password object). + + + + + a #GTlsPassword object + + + + location to place the length of the password. + + + + + + + + + + + + + + a #GTlsPassword object + + + + the value for the password + + + + + + the length of the password, or -1 + + + + a function to use to free the password. + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + 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 #GTlsConnection, +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 #GSocketConnection that is created +for UNIX domain sockets. + +It contains functions to do some of the UNIX socket specific +functionality like passing file descriptors. + +Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific +GIO interfaces, thus you have to use the `gio-unix-2.0.pc` +pkg-config file when using it. + + + 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 #GSocketControlMessage contains a #GCredentials instance. It +may be sent using g_socket_send_message() and received using +g_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 +g_unix_connection_send_credentials() and +g_unix_connection_receive_credentials(). To receive credentials of +a foreign process connected to a socket, use +g_socket_get_credentials(). + + + 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 and sent over a #GSocket in +the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() +and received using g_socket_receive_message(). + +Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO +interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config +file when using it. + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This #GSocketControlMessage contains a #GUnixFDList. +It may be sent using g_socket_send_message() and received using +g_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 g_unix_connection_send_fd() and +g_unix_connection_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 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GUnixInputStream implements #GInputStream 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 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. <filename>/media/cdrom</filename>). +This corresponds roughly to a mtab entry. + + + + Watches #GUnixMounts for changes. + + + Deprecated alias for g_unix_mount_monitor_get(). + +This function was never a true constructor, which is why it was +renamed. + Use g_unix_mount_monitor_get() instead. + + + a #GUnixMountMonitor. + + + + + Gets the #GUnixMountMonitor 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 g_object_unref() on the return value from under +the same main context as you called this function. + + + the #GUnixMountMonitor. + + + + + 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 #GUnixMountMonitor + + + + a integer with the limit in milliseconds to + poll for changes. + + + + + + Emitted when the unix mount points have changed. + + + + + + Emitted when the unix mounts have changed. + + + + + + + + + + Defines a Unix mount point (e.g. <filename>/dev</filename>). +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 #GUnixMount. + + + + a #GUnixMount. + + + + + + Makes a copy of @mount_point. + + + a new #GUnixMountPoint + + + + + a #GUnixMountPoint. + + + + + + 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 #GUnixMountPoint. + + + + + + Gets the file system type for the mount point. + + + a string containing the file system type. + + + + + a #GUnixMountPoint. + + + + + + Gets the mount path for a unix mount point. + + + a string containing the mount path. + + + + + a #GUnixMountPoint. + + + + + + Gets the options for the mount point. + + + a string containing the options. + + + + + a #GUnixMountPoint. + + + + + + Guesses whether a Unix mount point can be ejected. + + + %TRUE if @mount_point is deemed to be ejectable. + + + + + a #GUnixMountPoint + + + + + + Guesses the icon of a Unix mount point. + + + a #GIcon + + + + + a #GUnixMountPoint + + + + + + Guesses the name of a Unix mount point. +The result is a translated string. + + + A newly allocated string that must + be freed with g_free() + + + + + a #GUnixMountPoint + + + + + + Guesses the symbolic icon of a Unix mount point. + + + a #GIcon + + + + + a #GUnixMountPoint + + + + + + Checks if a unix mount point is a loopback device. + + + %TRUE if the mount point is a loopback. %FALSE otherwise. + + + + + a #GUnixMountPoint. + + + + + + Checks if a unix mount point is read only. + + + %TRUE if a mount point is read only. + + + + + a #GUnixMountPoint. + + + + + + Checks if a unix mount point is mountable by the user. + + + %TRUE if the mount point is user mountable. + + + + + a #GUnixMountPoint. + + + + + + + #GUnixOutputStream implements #GOutputStream 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 +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Support for UNIX-domain (also known as local) sockets. + +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 g_unix_socket_address_abstract_names_supported() +to see if abstract names are supported. + +Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO +interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file +when using it. + + + + 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 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][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][extending-gio]. + + + + + + + + + + + + Entry point for using GIO functionality. + + + Gets the default #GVfs for the system. + + + a #GVfs. + + + + + 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 an 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 an URI or a parse name as returned by g_file_get_parse_name() + + + + user data passed to the function + + + + + + The #GVolume interface represents user-visible objects that can be +mounted. Note, when porting from GnomeVFS, #GVolume is the moral +equivalent of #GnomeVFSDrive. + +Mounting a #GVolume instance is an asynchronous operation. For more +information about asynchronous operations, see #GAsyncResult and +#GTask. To mount a #GVolume, first call g_volume_mount() with (at +least) the #GVolume instance, optionally a #GMountOperation object +and a #GAsyncReadyCallback. + +Typically, one will only want to pass %NULL for the +#GMountOperation 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 #GAsyncResult instance will be +passed to the callback. That callback should then call +g_volume_mount_finish() with the #GVolume instance and the +#GAsyncResult data to see if the operation was completed +successfully. If an @error is present when g_volume_mount_finish() +is called, then it will be filled with any error information. + +## Volume Identifiers # {#volume-identifier} + +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 commandline). 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 g_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 + + + + + + + + + + + + + + + + + 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-identifier] 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-identifier] 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 + + + + + + + + + + + + + + + + + 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-identifier] 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-identifier] 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the name for the given @volume. The returned string should + be freed with g_free() when no longer needed. + + + + + a #GVolume + + + + + + + + + + a #GIcon. + The returned object should be unreffed with g_object_unref() + when no longer needed. + + + + + a #GVolume + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the @volume can be mounted. %FALSE otherwise + + + + + a #GVolume + + + + + + + + + + %TRUE if the @volume can be ejected. %FALSE otherwise + + + + + a #GVolume + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE, %FALSE if operation failed + + + + + a #GVolume + + + + a #GAsyncResult + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE, %FALSE if operation failed + + + + + pointer to a #GVolume + + + + a #GAsyncResult + + + + + + + + + + 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 + + + + + + + + + + a %NULL-terminated array + of strings containing kinds of identifiers. Use g_strfreev() to free. + + + + + + + a #GVolume + + + + + + + + + + %TRUE if the volume should be automatically mounted + + + + + a #GVolume + + + + + + + + + + the activation root of @volume + or %NULL. Use g_object_unref() to free. + + + + + a #GVolume + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the volume was successfully ejected. %FALSE otherwise + + + + + a #GVolume + + + + a #GAsyncResult + + + + + + + + + + Sorting key for @volume or %NULL if no such key is available + + + + + a #GVolume + + + + + + + + + + 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][g-main-context-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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Zlib decompression + + + + Creates a new #GZlibCompressor. + + + a new #GZlibCompressor + + + + + The format to use for the compressed data + + + + compression level (0-9), -1 for default + + + + + + Returns the #GZlibCompressor:file-info property. + + + a #GFileInfo, or %NULL + + + + + a #GZlibCompressor + + + + + + Sets @file_info in @compressor. If non-%NULL, and @compressor's +#GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, +it will be used to set the file name and modification time in +the GZIP header of the compressed data. + +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 g_converter_reset(). + + + + + + + a #GZlibCompressor + + + + a #GFileInfo + + + + + + If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is +%G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name +and modification time from the file info to the GZIP header. + + + + + + + + + + + + + + + + + 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 + + + + Zlib decompression + + + + Creates a new #GZlibDecompressor. + + + a new #GZlibDecompressor + + + + + The format to use for the compressed data + + + + + + Retrieves the #GFileInfo constructed from the GZIP header data +of compressed data processed by @compressor, or %NULL if @decompressor's +#GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, +or the header data was not fully processed yet, or it not present in the +data stream at all. + + + a #GFileInfo, or %NULL + + + + + a #GZlibDecompressor + + + + + + A #GFileInfo containing the information found in the GZIP header +of the data stream processed, or %NULL if the header was not yet +fully processed, is not present at all, or the compressor's +#GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP. + + + + + + + + + + + + + + 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-utf8 @action_name. +@action_name must not be %NULL. + + + %TRUE if @action_name is valid + + + + + an 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 g_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 '.'. + + + %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 g_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 #GVariant target value, or %NULL + + + + + + Creates a new #GAppInfo 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 for exact quoting rules. + + + new #GAppInfo for given command. + + + + + the commandline to use + + + + the application name, or %NULL to use @commandline + + + + flags that can specify details of the created #GAppInfo + + + + + + Gets a list of all of the applications currently registered +on this system. + +For desktop files, this includes applications that have +`NoDisplay=true` set or are excluded from display by means +of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). +The returned list does not include applications which have +the `Hidden` key set. + + + a newly allocated #GList of references to #GAppInfos. + + + + + + + Gets a list of all #GAppInfos for a given content type, +including the recommended and fallback #GAppInfos. See +g_app_info_get_recommended_for_type() and +g_app_info_get_fallback_for_type(). + + + #GList of #GAppInfos + for given @content_type or %NULL on error. + + + + + + + the content type to find a #GAppInfo for + + + + + + Gets the default #GAppInfo for a given content type. + + + #GAppInfo for given @content_type or + %NULL on error. + + + + + the content type to find a #GAppInfo for + + + + if %TRUE, the #GAppInfo is expected to + support URIs + + + + + + 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". + + + #GAppInfo for given @uri_scheme or %NULL on error. + + + + + a string containing a URI scheme. + + + + + + Gets a list of fallback #GAppInfos for a given content type, i.e. +those applications which claim to support the given content type +by MIME type subclassing and not directly. + + + #GList of #GAppInfos + for given @content_type or %NULL on error. + + + + + + + the content type to find a #GAppInfo for + + + + + + Gets a list of recommended #GAppInfos 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 g_app_info_set_as_last_used_for_type() has been +called. + + + #GList of #GAppInfos + for given @content_type or %NULL on error. + + + + + + + the content type to find a #GAppInfo 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 +g_app_info_launch_default_for_uri_async() instead. + + + %TRUE on success, %FALSE on error. + + + + + the uri to show + + + + an optional #GAppLaunchContext + + + + + + Async version of g_app_info_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 + + + + an optional #GAppLaunchContext + + + + a #GCancellable + + + + a #GAsyncReadyCallback 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 + + + + + a #GAsyncResult + + + + + + Removes all changes to the type associations done by +g_app_info_set_as_default_for_type(), +g_app_info_set_as_default_for_extension(), +g_app_info_add_supports_type() or +g_app_info_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][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(). + +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(). + +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 + + + + + + Starts acquiring @name on the bus specified by @bus_type and calls +@name_acquired_handler and @name_lost_handler when the name is +acquired respectively lost. Callbacks will be invoked in the +[thread-default main context][g-main-context-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, just call g_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 #GDBusConnection 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 g_bus_own_name() several times for the same name (unless +interleaved with calls to g_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 e.g. +g_dbus_connection_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 wants +to [own names][gdbus-owning-names] 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 an be used with + g_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 from the #GBusNameOwnerFlags enumeration + + + + handler to invoke when connected to the bus of type @bus_type or %NULL + + + + handler to invoke when @name is acquired or %NULL + + + + handler to invoke when @name is lost or %NULL + + + + user data to pass to handlers + + + + function for freeing @user_data or %NULL + + + + + + Like g_bus_own_name() but takes a #GDBusConnection instead of a +#GBusType. + + + an identifier (never 0) that an be used with + g_bus_unown_name() to stop owning the name + + + + + a #GDBusConnection + + + + the well-known name to own + + + + a set of flags from the #GBusNameOwnerFlags enumeration + + + + handler to invoke when @name is acquired or %NULL + + + + handler to invoke when @name is lost or %NULL + + + + user data to pass to handlers + + + + function for freeing @user_data or %NULL + + + + + + Version of g_bus_own_name_on_connection() using closures instead of +callbacks for easier binding in other languages. + + + an identifier (never 0) that an be used with + g_bus_unown_name() to stop owning the name. + + + + + a #GDBusConnection + + + + the well-known name to own + + + + a set of flags from the #GBusNameOwnerFlags enumeration + + + + #GClosure to invoke when @name is + acquired or %NULL + + + + #GClosure to invoke when @name is lost + or %NULL + + + + + + Version of g_bus_own_name() using closures instead of callbacks for +easier binding in other languages. + + + an identifier (never 0) that an be used with + g_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 from the #GBusNameOwnerFlags enumeration + + + + #GClosure to invoke when connected to + the bus of type @bus_type or %NULL + + + + #GClosure to invoke when @name is + acquired or %NULL + + + + #GClosure to invoke when @name is lost or + %NULL + + + + + + Stops owning a name. + + + + + + + an identifier obtained from g_bus_own_name() + + + + + + Stops watching a name. + + + + + + + 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 a owner respectively known to lose its +owner. Callbacks will be invoked in the +[thread-default main context][g-main-context-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][gdbus-watching-names]. +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 an 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 an 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 an 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 an 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. + + + + + + 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 string, 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 #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). + +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 (cf. g_dbus_error_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 #GError using g_dbus_error_new_for_dbus_error(). + +This function is typically only used in object mappings to put a +#GError on the wire. Regular applications should not use it. + + + A D-Bus error name (never %NULL). Free with g_free(). + + + + + A #GError. + + + + + + Gets the D-Bus error name used for @error, if any. + +This function is guaranteed to return a D-Bus error name for all +#GErrors returned from functions handling remote method calls +(e.g. g_dbus_connection_call_finish()) unless +g_dbus_error_strip_remote_error() has been used on @error. + + + an allocated string or %NULL if the D-Bus error name + could not be found. Free with g_free(). + + + + + a #GError + + + + + + Checks if @error represents an error received via D-Bus from a remote peer. If so, +use g_dbus_error_get_remote_error() to get the name of the error. + + + %TRUE if @error represents an error from a remote peer, +%FALSE otherwise. + + + + + A #GError. + + + + + + Creates a #GError based on the contents of @dbus_error_name and +@dbus_error_message. + +Errors registered with g_dbus_error_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 g_dbus_error_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 g_dbus_error_encode_gerror() +the error domain and code encoded in the name is used to +create the #GError. Also, @dbus_error_name is added to the error message +such that it can be recovered with g_dbus_error_get_remote_error(). + +Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR +in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is +added to the error message such that it can be recovered with +g_dbus_error_get_remote_error(). + +In all three cases, @dbus_error_name can always be recovered from the +returned #GError using the g_dbus_error_get_remote_error() function +(unless g_dbus_error_strip_remote_error() hasn't been used on the returned error). + +This function is typically only used in object mappings to prepare +#GError instances for applications. Regular applications should not use +it. + + + An allocated #GError. Free with g_error_free(). + + + + + D-Bus error name. + + + + D-Bus error message. + + + + + + + + + + + Creates an association to map between @dbus_error_name and +#GErrors specified by @error_domain and @error_code. + +This is typically done in the routine that returns the #GQuark for +an error domain. + + + %TRUE if the association was created, %FALSE if it already +exists. + + + + + A #GQuark for a error domain. + + + + An error code. + + + + A D-Bus error name. + + + + + + Helper function for associating a #GError error domain with D-Bus error names. + + + + + + + The error domain name. + + + + A pointer where to store the #GQuark. + + + + A pointer to @num_entries #GDBusErrorEntry struct items. + + + + + + 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. + + + + + A #GError. + + + + + + Destroys an association previously set up with g_dbus_error_register_error(). + + + %TRUE if the association was destroyed, %FALSE if it wasn't found. + + + + + A #GQuark for a error domain. + + + + An error code. + + + + A D-Bus error name. + + + + + + Generate a D-Bus GUID that can be used with +e.g. g_dbus_connection_new(). + +See the D-Bus specification regarding what strings are valid D-Bus +GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + + + 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'][G-VARIANT-TYPE-INT32:CAPS]. 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 %NULL 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. + + + + + + Checks if @string is a D-Bus GUID. + +See the D-Bus specification regarding what strings are valid D-Bus +GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + + + %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. + + + + + + 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 + + + + + + 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 + + + + + + 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() + + + + + + 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. + + + + + + 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 as soon as the call which sets it + + + #GIOErrorEnum value for the given errno.h error number. + + + + + Error number as defined in errno.h. + + + + + + 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 implementes 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 implementes 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][io-priority] +of the request. + + + + optional #GCancellable object, %NULL to ignore. + + + + + + Creates a keyfile-backed #GSettingsBackend. + +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 settings the key "/apps/example/enabled" to a value +of %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 #GSettingsBackend + + + + + the filename of the keyfile + + + + the path under which all settings keys appear + + + + the group name corresponding to + @root_path, or %NULL + + + + + + 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 + + + + + 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. + + + + + + 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. + + + + + Gets the #GResolver Error Quark. + + a #GQuark. + + + + + Gets the #GResource Error Quark. + + a #GQuark + + + + + Loads a binary resource bundle and creates a #GResource 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 g_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 g_mapped_file_new() will be +returned. + + + a new #GResource, 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 g_strfreev(). + +@lookup_flags controls the behaviour of the lookup. + + + an array of constant strings + + + + + + + A pathname inside the resource + + + + A #GResourceLookupFlags + + + + + + 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 pathname inside the resource + + + + A #GResourceLookupFlags + + + + 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 #GResourceFlags about the file, + or %NULL if the flags are not needed + + + + + + Looks for a file at the specified @path in the set of +globally registered resources and returns a #GBytes 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 GBytes. + +For uncompressed resource files this is a pointer directly into +the resource bundle, which is typically in some readonly 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. + + + #GBytes or %NULL on error. + Free the returned object with g_bytes_unref() + + + + + A pathname inside the resource + + + + A #GResourceLookupFlags + + + + + + Looks for a file at the specified @path in the set of +globally registered resources and returns a #GInputStream +that lets you read the data. + +@lookup_flags controls the behaviour of the lookup. + + + #GInputStream or %NULL on error. + Free the returned object with g_object_unref() + + + + + A pathname inside the resource + + + + A #GResourceLookupFlags + + + + + + 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 g_resources_lookup_data(). + + + + + + + A #GResource + + + + + + Unregisters the resource from the process-global set of resources. + + + + + + + A #GResource + + + + + + 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 + + + + + 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 + + + + + + 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. + + + + + 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. + + + + + 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. + + + + + a file system type, e.g. `procfs` or `tmpfs` + + + + + + Gets a #GUnixMountEntry 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 g_unix_mounts_changed_since(). + +If more mounts have the same mount path, the last matching mount +is returned. + + + a #GUnixMountEntry. + + + + + path for a possible unix mount. + + + + guint64 to contain a timestamp. + + + + + + Compares two unix mounts. + + + 1, 0 or -1 if @mount1 is greater than, equal to, +or less than @mount2, respectively. + + + + + first #GUnixMountEntry to compare. + + + + second #GUnixMountEntry to compare. + + + + + + Makes a copy of @mount_entry. + + + a new #GUnixMountEntry + + + + + a #GUnixMountEntry. + + + + + + Gets a #GUnixMountEntry 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 g_unix_mounts_changed_since(). + +If more mounts have the same mount path, the last matching mount +is returned. + + + a #GUnixMountEntry. + + + + + file path on some unix mount. + + + + guint64 to contain a timestamp. + + + + + + Frees a unix mount. + + + + + + + a #GUnixMountEntry. + + + + + + Gets the device path for a unix mount. + + + a string containing the device path. + + + + + a #GUnixMount. + + + + + + Gets the filesystem type for the unix mount. + + + a string containing the file system type. + + + + + a #GUnixMount. + + + + + + Gets the mount path for a unix mount. + + + the mount path for @mount_entry. + + + + + input #GUnixMountEntry 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 g_unix_mount_point_get_options(), but it takes +a #GUnixMountEntry as an argument. + + + a string containing the options, or %NULL if not +available. + + + + + a #GUnixMountEntry. + + + + + + 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 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 #GUnixMountEntry. + + + + + + Guesses whether a Unix mount can be ejected. + + + %TRUE if @mount_entry is deemed to be ejectable. + + + + + a #GUnixMountEntry + + + + + + Guesses the icon of a Unix mount. + + + a #GIcon + + + + + a #GUnixMountEntry + + + + + + Guesses the name of a Unix mount. +The result is a translated string. + + + A newly allocated string that must + be freed with g_free() + + + + + a #GUnixMountEntry + + + + + + Guesses whether a Unix mount should be displayed in the UI. + + + %TRUE if @mount_entry is deemed to be displayable. + + + + + a #GUnixMountEntry + + + + + + Guesses the symbolic icon of a Unix mount. + + + a #GIcon + + + + + a #GUnixMountEntry + + + + + + Checks if a unix mount is mounted read only. + + + %TRUE if @mount_entry is read only. + + + + + a #GUnixMount. + + + + + + Checks if a Unix mount is a system mount. This is the Boolean OR of +g_unix_is_system_fs_type(), g_unix_is_system_device_path() and +g_unix_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. + + + + + a #GUnixMount. + + + + + + Checks if the unix mount points have changed since a given unix time. + + + %TRUE if the mount points have changed since @time. + + + + + guint64 to contain a timestamp. + + + + + + Gets a #GList of #GUnixMountPoint containing 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 +g_unix_mount_points_changed_since(). + + + + a #GList of the UNIX mountpoints. + + + + + + + guint64 to contain a timestamp. + + + + + + Checks if the unix mounts have changed since a given unix time. + + + %TRUE if the mounts have changed since @time. + + + + + guint64 to contain a timestamp. + + + + + + Gets a #GList of #GUnixMountEntry containing 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 g_unix_mounts_changed_since(). + + + + a #GList of the UNIX mounts. + + + + + + + guint64 to contain a timestamp, or %NULL + + + + + + diff --git a/gir-files/Graphene-1.0.gir b/gir-files/Graphene-1.0.gir new file mode 100644 index 0000000..7b9b701 --- /dev/null +++ b/gir-files/Graphene-1.0.gir @@ -0,0 +1,7646 @@ + + + + + + + + + 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 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 + + + + + + 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 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 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 left-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 + + + + + + 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 + + + Rotate in the Y, Z, and X order + + + Rotate in the Z, X, and Y order + + + Rotate in the X, Z, and Y order + + + Rotate in the Y, X, and Z order + + + Rotate in the Z, Y, and X order + + + + 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 + + + + + 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. + + + 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 check +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 + + + + + + + + + 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. + + + + + + + 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 a #graphene_rect_t using the given matrix. + + + + + + + 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 containing fully 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. + + + + + + + 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. + + + + + + + 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. + + + + + + + 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 + + + + + + + + + + + + + + + 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 + + + + + + + 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 + + + + + + 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 + + + + + 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. + + + + + + + a #graphene_quaternion_t + + + + return location for the inverted + quaternion + + + + + + Normalizes a #graphene_quaternion_t. + + + + + + + a #graphene_quaternion_t + + + + return location for the normalized + quaternion + + + + + + 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 + + + + + + + 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 from the origin of the given ray to the given point. + + + 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 + + + + + + + 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 + + + + + + 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 contain the original rectangle. + +This function is the equivalent of calling `floor` on +the coordinates of the origin, and `ceil` on the size. + + + + + + + a #graphene_rect_t + + + + return location for the + rounded rectangle + + + + + + 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. + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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 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. + + + + + Evaluates to the number of components of a #graphene_vec3_t. + + + + + Evaluates to the number of components of a #graphene_vec4_t. + + + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + 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_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 + + + + + + + + + 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 + + + + + diff --git a/gir-files/Gsk-4.0.gir b/gir-files/Gsk-4.0.gir new file mode 100644 index 0000000..a022e42 --- /dev/null +++ b/gir-files/Gsk-4.0.gir @@ -0,0 +1,2709 @@ + + + + + + + + + + + The blend modes available for render nodes. + +The implementation of each blend mode is deferred to the +rendering pipeline. + + The default blend mode, which specifies no blending + + + The source color is multiplied by the destination + and replaces the destination + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + ... + + + + + + 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 gdk_renderer_realize(). + +This function is only available when GTK was compiled with Broadway +support. + + + a new Broadway renderer. + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + The corner indices used by #GskRoundedRect. + + The top left corner + + + The top right corner + + + The bottom right corner + + + The bottom left corner + + + + + + Creates a new #GskRenderer using OpenGL. This is the default renderer +used by GTK. + + + a new GL renderer + + + + + + + + + + + + + + + + + + + + + + + + + + The `GskRenderNode` structure contains only private data. + + + Draw the contents of @node to the given cairo context. + +Typically, you'll use this function to implement fallback rendering +of #GskRenderNodes on an intermediate Cairo context, instead of using +the drawing context associated to a #GdkSurface's rendering buffer. + +For advanced nodes that cannot be supported using Cairo, in particular +for nodes doing 3D operations, this function may fail. + + + + + + + a #GskRenderNode + + + + cairo context to draw to + + + + + + Retrieves the boundaries of the @node. The node will not draw outside +of its boundaries. + + + + + + + a #GskRenderNode + + + + return location for the boundaries + + + + + + Returns the type of the @node. + + + the type of the #GskRenderNode + + + + + a #GskRenderNode + + + + + + Acquires a reference on the given #GskRenderNode. + + + the #GskRenderNode with an additional reference + + + + + a #GskRenderNode + + + + + + 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 #GskRenderNode + + + + + + This function is equivalent to calling gsk_render_node_serialize() +followed by g_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 #GskRenderNode + + + + the file to save it to. + + + + + + Loads data previously created via gsk_render_node_serialize(). For a +discussion of the supported format, see that function. + + + a new #GskRenderNode or %NULL on + error. + + + + + the bytes containing the data + + + + + + + + + + + + + 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 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 + + + + + + + + Creates an appropriate #GskRenderer instance for the given @surface. + +The renderer will be realized when it is returned. + + + a #GskRenderer + + + + + a #GdkSurface + + + + + + Retrieves the #GdkSurface set using gsk_renderer_realize(). If the renderer +has not been realized yet, %NULL will be returned. + + + a #GdkSurface + + + + + a #GskRenderer + + + + + + Checks whether the @renderer is realized or not. + + + %TRUE if the #GskRenderer was realized, and %FALSE otherwise + + + + + a #GskRenderer + + + + + + Creates the resources needed by the @renderer to render the scene +graph. + + + + + + + a #GskRenderer + + + + the #GdkSurface renderer will be used on + + + + + + Renders the scene graph, described by a tree of #GskRenderNode instances, +ensuring that the given @region gets redrawn. + +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 #GskRenderer + + + + a #GskRenderNode + + + + the #cairo_region_t that must be redrawn or %NULL + for the whole window + + + + + + Renders the scene graph, described by a tree of #GskRenderNode instances, +to a #GdkTexture. + +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 #GdkTexture with the rendered contents of @root. + + + + + a realized #GdkRenderer + + + + a #GskRenderNode + + + + the section to draw or %NULL to use @root's bounds + + + + + + Releases all the resources created by gsk_renderer_realize(). + + + + + + + a #GskRenderer + + + + + + + + + + + + + + + + A rectangular region with rounded corners. + +Application code should normalize rectangles using gsk_rounded_rect_normalize(); +this function will ensure that the bounds of the rectanlge 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 bounds of the rectangle + + + + the size of the 4 rounded corners + + + + + + Checks if the given @point is inside the rounded rectangle. This function +returns %FALSE if the point is in the rounded corner areas. + + + %TRUE if the @point is inside the rounded rectangle + + + + + a #GskRoundedRect + + + + the point to check + + + + + + Checks if the given @rect is contained inside the rounded rectangle. +This function returns %FALSE if @rect extends into one of the rounded +corner areas. + + + %TRUE if the @rect is fully contained inside the rounded rectangle + + + + + a #GskRoundedRect + + + + the rectangle to check + + + + + + Initializes the given #GskRoundedRect with the given values. + +This function will implicitly normalize the #GskRoundedRect +before returning. + + + the initialized rectangle + + + + + The #GskRoundedRect 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 @self using the given @src rectangle. + +This function will not normalize the #GskRoundedRect, so +make sure the source is normalized. + + + the initialized rectangle + + + + + a #GskRoundedRect + + + + a #GskRoundedRect + + + + + + Initializes @self to the given @bounds and sets the radius of all +four corners to @radius. + + + the initialized rectangle + + + + + a #GskRoundedRect + + + + a #graphene_rect_t + + + + the border radius + + + + + + Checks if part of the given @rect is contained inside the rounded rectangle. +This function returns %FALSE if @rect only extends into one of the rounded +corner areas but not into the rounded rectangle itself. + + + %TRUE if the @rect intersects with the rounded rectangle + + + + + a #GskRoundedRect + + + + the rectangle to check + + + + + + Checks if all corners of @self are right angles and the +rectangle covers all of its bounds. + +This information can be used to decide if gsk_clip_node_new() +or gsk_rounded_clip_node_new() should be called. + + + %TRUE if the rectangle is rectilinear + + + + + the #GskRoundedRect to check + + + + + + Normalizes the passed rectangle. + +this function will ensure that the bounds of the rectanlge are normalized +and ensure that the corner values are positive and the corners do not overlap. + + + the normalized rectangle + + + + + a #GskRoundedRect + + + + + + Offsets the bound's origin by @dx and @dy. + +The size and corners of the rectangle are unchanged. + + + the offset rectangle + + + + + a #GskRoundedRect + + + + the horizontal offset + + + + the vertical offset + + + + + + Shrinks (or grows) the given 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 rectangles if you pass +negative values for the @top, @right, @bottom or @left. + + + the resized #GskRoundedRect + + + + + The #GskRoundedRect 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + The `GskTransform` structure contains only private data. + + + + + + + + + Checks two matrices for equality. Note that matrices need to be literally +identical in their operations, it is not enough that they return the +same result in gsk_transform_to_matrix(). + + + %TRUE if the two matrices can be proven to be equal + + + + + the first matrix + + + + the second matrix + + + + + + Returns the category this transform belongs to. + + + The category of the transform + + + + + A #GskTransform + + + + + + 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. + + + The inverted transform or %NULL if the transform + cannot be inverted. + + + + + Transform to invert + + + + + + Multiplies @next with the given @matrix. + + + The new matrix + + + + + the next transform + + + + the matrix to multiply @next with + + + + + + 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. + + + The new matrix + + + + + the next transform + + + + distance of the z=0 plane. Lower values give a more + flattened pyramid and therefore a more pronounced + perspective effect. + + + + + + Converts @self into a human-readable string representation suitable +for printing that can later be parsed with gsk_transform_parse(). + + + + + + + a #GskTransform + + + + The string to print into + + + + + + Acquires a reference on the given #GskTransform. + + + the #GskTransform with an additional reference + + + + + a #GskTransform + + + + + + Rotates @next @angle degrees in 2D - or in 3Dspeak, around the z axis. + + + The new matrix + + + + + the next transform + + + + the rotation angle, in degrees (clockwise) + + + + + + Rotates @next @angle degrees around @axis. + +For a rotation in 2D space, use gsk_transform_rotate(). + + + The new matrix + + + + + the next transform + + + + the rotation angle, in degrees (clockwise) + + + + The rotation axis + + + + + + Scales @next in 2-dimensional space by the given factors. +Use gsk_transform_scale_3d() to scale in all 3 dimensions. + + + The new matrix + + + + + the next transform + + + + scaling factor on the X axis + + + + scaling factor on the Y axis + + + + + + Scales @next by the given factors. + + + The new matrix + + + + + the next transform + + + + scaling factor on the X axis + + + + scaling factor on the Y axis + + + + scaling factor on the Z axis + + + + + + Converts a #GskTransform 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 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 #GskTransform +and a matrix type from other 2D drawing libraries, in particular +Cairo. + + + + + + + a 2D #GskTransform + + + + 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 #GskTransform to 2D affine transformation +factors. +@self must be a 2D transformation. If you are not +sure, use gsk_transform_get_category() >= +%GSK_TRANSFORM_CATEGORY_2D_AFFINE to check. + + + + + + + a #GskTransform + + + + 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 actual value of @self and stores it in @out_matrix. +The previous value of @out_matrix will be ignored. + + + + + + + a #GskTransform + + + + The matrix to set + + + + + + Converts a matrix into a string that is suitable for +printing and can later be parsed with gsk_transform_parse(). + +This is a wrapper around gsk_transform_print(), see that function +for details. + + + A new string for @self + + + + + a #GskTransform + + + + + + Converts a #GskTransform 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 #GskTransform + + + + 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. + + + The new matrix + + + + + Transform to apply @other to + + + + Transform to apply + + + + + + Transforms a #graphene_rect_t using the given matrix @m. The +result is the bounding box containing the coplanar quad. + + + + + + + a #GskTransform + + + + a #graphene_rect_t + + + + return location for the bounds + of the transformed rectangle + + + + + + Translates @next in 2dimensional space by @point. + + + The new matrix + + + + + the next transform + + + + the point to translate the matrix by + + + + + + Translates @next by @point. + + + The new matrix + + + + + the next transform + + + + the point to translate the matrix by + + + + + + Releases a reference on the given #GskTransform. + +If the reference was the last, the resources associated to the @self are +freed. + + + + + + + a #GskTransform + + + + + + Gets the child node that is getting transformed by the given @node. + + + The child that is getting transformed + + + + + a transform @GskRenderNode + + + + + + + + + + + + + + + + + Creates a #GskRenderNode that will transform the given @child +with the given @transform. + + + A new #GskRenderNode + + + + + The node to transform + + + + The transform to apply + + + + + + Parses the given @string into a transform and puts it in +@out_transform. Strings printed via 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 + + + + The location to put the transform in + + + + + + + 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 +mutliplication 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a render node that blurs the child. + + + + + + + the child node to blur + + + + the blur radius + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 cairo #GskRenderNode + + + + + + Creates a #GskRenderNode that will render a cairo surface +into the area given by @bounds. You can draw to the cairo +surface using gsk_cairo_node_get_draw_context() + + + A new #GskRenderNode + + + + + the rectangle to render to + + + + + + + + + + + + + + + + + Gets the child node that is getting clipped by the given @node. + + + The child that is getting clipped + + + + + a clip @GskRenderNode + + + + + + 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 its colors modified by the given @node. + + + The child that is getting its colors modified + + + + + a color matrix @GskRenderNode + + + + + + Creates a #GskRenderNode that will drawn the @child with reduced +@color_matrix. + +In particular, the node will transform the operation + pixel = color_matrix * pixel + color_offset +for every pixel. + + + A new #GskRenderNode + + + + + The node to draw + + + + The matrix to apply + + + + Values to add to the 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 + + + + + + + + + + + + + + + + + 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 + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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] + + + + + + Gets the child node that is getting debug by the given @node. + + + The child that is getting debug + + + + + a debug @GskRenderNode + + + + + + Gets the debug message that was set on this node + + + The debug message + + + + + a debug #GskRenderNode + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 number of elements in @color_stops + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gets the child node that is getting opacityed by the given @node. + + + The child that is getting opacityed + + + + + a opacity @GskRenderNode + + + + + + + + + + + + + + + + + Creates a #GskRenderNode that will drawn the @child with reduced +@opacity. + + + A new #GskRenderNode + + + + + The node to draw + + + + The opacity to apply + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + 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 number of elements in @color_stops + + + + + + Gets the child node that is getting clipped by the given @node. + + + The child that is getting clipped + + + + + a clip @GskRenderNode + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a render node that renders the given glyphs, +Note that @color may not be used if the font contains +color glyphs. + + + a new text node, or %NULL + + + + + the #PangoFont containing the glyphs + + + + the #PangoGlyphString to render + + + + the foreground color to render with + + + + the x coordinate at which to put the baseline + + + + the y coordinate at wihch to put the baseline + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the #GdkTexture + + + + + a #GskRenderNode + + + + + + Creates a #GskRenderNode that will render the given +@texture into the area given by @bounds. + + + A new #GskRenderNode + + + + + the #GdkTexture + + + + the rectangle to render the texture into + + + + + + Gets the child node that is getting transformed by the given @node. + + + The child that is getting transformed + + + + + a transform @GskRenderNode + + + + + + + + + + + + + + + + + Creates a #GskRenderNode that will transform the given @child +with the given @transform. + + + A new #GskRenderNode + + + + + The node to transform + + + + The transform to apply + + + + + + Parses the given @string into a transform and puts it in +@out_transform. Strings printed via 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 + + + + The location to put the transform in + + + + + + diff --git a/gir-files/Gtk-3.0.gir b/gir-files/Gtk-3.0.gir new file mode 100644 index 0000000..5c42227 --- /dev/null +++ b/gir-files/Gtk-3.0.gir @@ -0,0 +1,154109 @@ + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + 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. ## +|[ +<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. + + + + + + + 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. + + + + + + + + + the action name, or %NULL if none is set + + + + + a #GtkActionable widget + + + + + + + + + + + + + + a #GtkActionable widget + + + + an action name, or %NULL + + + + + + + + + + the current target value + + + + + a #GtkActionable widget + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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://git.gnome.org/browse/gtk+/tree/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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + a #GtkBuildable + + + + name to set + + + + + + + + + + the name set with gtk_buildable_set_name() + + + + + a #GtkBuildable + + + + + + + + + + + + + + a #GtkBuildable + + + + a #GtkBuilder + + + + child to add + + + + kind of child or %NULL + + + + + + + + + + + + + + a #GtkBuildable + + + + a #GtkBuilder + + + + name of property + + + + value of property + + + + + + + + + + the constructed child + + + + + A #GtkBuildable + + + + #GtkBuilder used to construct this object + + + + name of child to construct + + + + + + + + + + %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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + a #GtkBuildable + + + + a #GtkBuilder + + + + child object or %NULL for non-child tags + + + + the name of the tag + + + + user data created in custom_tag_start + + + + + + + + + + + + + + a #GtkBuildable + + + + a #GtkBuilder + + + + + + + + + + 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://git.gnome.org/browse/gtk+/tree/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 implement 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” +propery 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 + +|[ +<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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + The #GtkButton you want to send the signal to. + + + + + + + + + + + + + + The #GtkButton you want to send the signal to. + + + + + + + + + + + + + + The #GtkButton you want to send the signal to. + + + + + + + + + + + + + + The #GtkButton you want to send the signal to. + + + + + + + + + + + + + + The #GtkButton you want to send the signal to. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkCellArea + + + + the #GtkCellRenderer to add to @area + + + + + + + + + + + + + + a #GtkCellArea + + + + the #GtkCellRenderer to remove from @area + + + + + + + + + + + + + + a #GtkCellArea + + + + the #GtkCellCallback to call + + + + user provided data pointer + + + + + + + + + + + + + + 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 + + + + + + + + + + %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. + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + 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 + + + + + + + + + + a newly created #GtkCellAreaContext which can be used with @area. + + + + + a #GtkCellArea + + + + + + + + + + a newly created #GtkCellAreaContext copy of @context. + + + + + a #GtkCellArea + + + + the #GtkCellAreaContext to copy + + + + + + + + + + The #GtkSizeRequestMode preferred by @area. + + + + + a #GtkCellArea + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %TRUE if focus remains inside @area as a result of this call. + + + + + a #GtkCellArea + + + + the #GtkDirectionType + + + + + + + + + + whether @area can do anything when activated. + + + + + a #GtkCellArea + + + + + + + + + + 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(). + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + a #GtkCellAreaContext + + + + + + + + + + + + + + a #GtkCellAreaContext + + + + a proposed width for allocation + + + + location to store the minimum height, + or %NULL + + + + location to store the natural height, + or %NULL + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + A #GtkCellEditable + + + + + + + + + + + + + + A #GtkCellEditable + + + + + + + + + + + + + + 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: +|[ +<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: + +|[ +<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() + + + + + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer + + + + %TRUE if @cell is to be given extra space allocated to @cell_layout + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer + + + + %TRUE if @cell is to be given extra space allocated to @cell_layout + + + + + + + + + + + + + + a #GtkCellLayout + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer + + + + an attribute on the renderer + + + + the column position on the model to get the attribute from + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer + + + + the #GtkCellLayoutDataFunc to use, or %NULL + + + + user data for @func + + + + destroy notify for @func_data + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer to clear the attribute mapping on + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer to reorder + + + + new position to insert @cell at + + + + + + + + + + + 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 + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + +If the mode is set to %GTK_CELL_RENDERER_ACCEL_MODE_MODIFIER_TAP +then bare modifiers can be set as accelerators by tapping (ie: +pressing and immediately releasing) them. + + + + 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 +GTK_CELL_RENDERER_ACCEL_MODE_MODIFIER_TAP: Bare modifiers mode + + + + + + + + + + + + + + + + + The #GtkSizeRequestMode preferred by this renderer. + + + + + a #GtkCellRenderer instance + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + %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 + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + a #GtkCheckMenuItem. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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: +|[ +<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: +|[ +<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 + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + a #GtkContainer + + + + a widget to be placed inside @container + + + + + + + + + + + + + + a #GtkContainer + + + + a current child of @container + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkContainer + + + + + + + a callback + + + + callback user data + + + + + + + + + + + + + + a #GtkContainer + + + + a #GtkWidget, or %NULL + + + + + + + + + + a #GType. + + + + + a #GtkContainer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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: +|[ +<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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + a #GtkDialog + + + + response ID + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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. + + + + + + + + + + Sets the flags conditioning scroll controller behavior. + + + + + + + + + + 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: +|[ +<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 + + + + + + + + + + + + + + + + + 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. + + + + + + + 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 + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 open() or 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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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: +|[ +<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: +|[ +<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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 don’t need first-child or last-child styling, and want your code +to be future-proof, the recommendation is to switch to #GtkGrid instead +of nested boxes. For more information about migrating to #GtkGrid, +see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. + + + + + + Creates a new #GtkHBox. + You can use gtk_box_new() with %GTK_ORIENTATION_HORIZONTAL instead, + which is a quick and easy change. But the recommendation is to switch to + #GtkGrid, since #GtkBox is going to go away eventually. + See [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + 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. + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %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. + + + + + + + + + + + + + + a #GtkIMContext + + + + the client window. This may be %NULL to indicate + that the previous client window no longer exists. + + + + + + + + + + + + + + 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. + + + + + + + + + + %TRUE if the input method handled the key event. + + + + + a #GtkIMContext + + + + the key event + + + + + + + + + + + + + + a #GtkIMContext + + + + + + + + + + + + + + a #GtkIMContext + + + + + + + + + + + + + + a #GtkIMContext + + + + + + + + + + + + + + a #GtkIMContext + + + + new location + + + + + + + + + + + + + + a #GtkIMContext + + + + whether the IM context should use the preedit string. + + + + + + + + + + + + + + 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. + + + + + + + + + + %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. + +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 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 + (cannot be greater than #GTK_MAX_COMPOSE_LEN) + + + + 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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + 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: +|[ +<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. + + + + 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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A GtkListBox is a vertical container that 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 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Select all children of @box, if the selection mode allows it. + + + + + + + a #GtkListBox + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkListBox + + + + + + + + + + + + + + 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="C" --> +<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: +|[ +<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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + the menu item + + + + + + + + + + + + + + + + + + + + + + + + + + + the menu item + + + + the requisition to use as signal data. + + + + + + + + + + + + + + the menu item. + + + + the allocation to use as signal data. + + + + + + + + + + + + + + a #GtkMenuItem + + + + the text you want to set + + + + + + + + + + The text in the @menu_item label. This is the internal + string used by the label, and must not be modified. + + + + + a #GtkMenuItem + + + + + + + + + + + + + + the menu item + + + + + + + + + + + + + + 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: +|[ +<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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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_nautilus_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: +|[ +<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. + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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 + + + + + + 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 + +|[ +<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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #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 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 + + + + + + + + + + + + + + + + + %TRUE if the URI was found. + + + + + a #GtkRecentChooser + + + + a URI + + + + + + + + + + a newly allocated string holding a URI. + + + + + a #GtkRecentChooser + + + + + + + + + + %TRUE if @uri was found. + + + + + a #GtkRecentChooser + + + + a URI + + + + + + + + + + + + + + a #GtkRecentChooser + + + + a URI + + + + + + + + + + + + + + a #GtkRecentChooser + + + + + + + + + + + + + + a #GtkRecentChooser + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkRecentChooser + + + + a #GtkRecentFilter + + + + + + + + + + + + + + a #GtkRecentChooser + + + + a #GtkRecentFilter + + + + + + + + + + A singly linked list + of #GtkRecentFilter objects. You + should just free the returned list using g_slist_free(). + + + + + + + a #GtkRecentChooser + + + + + + + + + + + + + + a #GtkRecentChooser + + + + the comparison function + + + + user data to pass to @sort_func, or %NULL + + + + destroy notifier for @sort_data, or %NULL + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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: +|[ +<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. + + + + + + + + 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, makes +that child scrollable 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 +#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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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. + + + 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. + + + %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: +|[ +<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. + + + + + + + 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 + + + + + + + + + + + + + + + a #GtkStyleProperties containing the +style settings affecting @path + + + + + a #GtkStyleProvider + + + + #GtkWidgetPath to query + + + + + + + + + + %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 + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + 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] +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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkTextBuffer + + + + location to insert the pixbuf + + + + a #GdkPixbuf + + + + + + + + + + + + + + a #GtkTextBuffer + + + + location to insert the anchor + + + + a #GtkTextChildAnchor + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkTextBuffer + + + + a #GtkTextTag + + + + one bound of range to be tagged + + + + other bound of range to be tagged + + + + + + + + + + + + + + a #GtkTextBuffer + + + + a #GtkTextTag + + + + one bound of range to be untagged + + + + other bound of range to be untagged + + + + + + + + + + + + + + a #GtkTextBuffer + + + + + + + + + + + + + + a #GtkTextBuffer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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] +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] +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] +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] +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: +|[ +<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] +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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + the current orientation of @shell + + + + + a #GtkToolShell + + + + + + + + + + the current style of @shell + + + + + a #GtkToolShell + + + + + + + + + + The relief style of buttons on @shell. + + + + + a #GtkToolShell + + + + + + + + + + + + + + a #GtkToolShell + + + + + + + + + + the current text orientation of @shell + + + + + a #GtkToolShell + + + + + + + + + + the current text alignment of @shell + + + + + a #GtkToolShell + + + + + + + + + + the current ellipsize mode of @shell + + + + + a #GtkToolShell + + + + + + + + + + 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 + + + + + + + + + + + + + + + whether a new row was created before position @dest + + + + + a #GtkTreeDragDest + + + + row to drop in front of + + + + data to drop + + + + + + + + + + %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 + + + + + + + + + + + + + + + %TRUE if the row can be dragged + + + + + a #GtkTreeDragSource + + + + row on which user is initiating a drag + + + + + + + + + + %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 + + + + + + + + + + %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 + + + + + + Creates a new #GtkTreeModel, with @child_model as the child model. + + + A new #GtkTreeModel. + + + + + A #GtkTreeModel + + + + + + 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() + + + + + + + + + + + + + + + + + + a #GtkTreeModel + + + + a #GtkTreePath-struct pointing to the changed row + + + + a valid #GtkTreeIter-struct pointing to the changed row + + + + + + + + + + + + + + a #GtkTreeModel + + + + a #GtkTreePath-struct pointing to the inserted row + + + + a valid #GtkTreeIter-struct pointing to the inserted row + + + + + + + + + + + + + + a #GtkTreeModel + + + + a #GtkTreePath-struct pointing to the changed row + + + + a valid #GtkTreeIter-struct pointing to the changed row + + + + + + + + + + + + + + a #GtkTreeModel + + + + a #GtkTreePath-struct pointing to the previous location of + the deleted row + + + + + + + + + + + + + + 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` + + + + + + + + + + the flags supported by this interface + + + + + a #GtkTreeModel + + + + + + + + + + the number of columns + + + + + a #GtkTreeModel + + + + + + + + + + the type of the column + + + + + a #GtkTreeModel + + + + the column index + + + + + + + + + + %TRUE, if @iter was set + + + + + a #GtkTreeModel + + + + the uninitialized #GtkTreeIter-struct + + + + the #GtkTreePath-struct + + + + + + + + + + a newly-created #GtkTreePath-struct + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + + + + + + + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + the column to lookup the value at + + + + an empty #GValue to set + + + + + + + + + + %TRUE if @iter has been changed to the next node + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + + + + + + + %TRUE if @iter has been changed to the previous node + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + + + + + + + %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 + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct to test for children + + + + + + + + + + the number of children of @iter + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct, or %NULL + + + + + + + + + + %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 + + + + + + + + + + %TRUE, if @iter is set to the parent of @child + + + + + a #GtkTreeModel + + + + the new #GtkTreeIter-struct to set to the parent + + + + the #GtkTreeIter-struct + + + + + + + + + + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + + + + + + + + + + + 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); +} +]| + + + + + + 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). + + + + + + + + + + + + + + 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. @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. + + + TRUE, if there is a selected node. + + + + + A #GtkTreeSelection. + + + + A pointer to set to the #GtkTreeModel, or NULL. + + + + The #GtkTreeIter, or NULL. + + + + + + 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); +]| + + + A #GList containing a #GtkTreePath for each selected row. + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + A #GtkTreeSortable + + + + + + + + + + %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 + + + + + + + + + + + + + + A #GtkTreeSortable + + + + the sort column id to set + + + + The sort order of the column + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + 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: +|[ +<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] +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: +|[ +<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] +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] +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() + + + + + + + + + + + + + + + + + + + + + + + > 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. + +A #GtkUIManager constructs a user interface (menus and toolbars) from +one or more UI definitions, which reference actions from one or more +action groups. + +# 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 # + +|[ +<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 + +|[ +<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 instead, which is a +very quick and easy change. If you have derived your own classes from +GtkVBox, you can simply 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 don’t need first-child or last-child styling and want your code +to be future-proof, the recommendation is to switch to #GtkGrid instead +of nested boxes. For more information about migrating to #GtkGrid, +see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. + + + + + + Creates a new #GtkVBox. + You can use gtk_box_new() with %GTK_ORIENTATION_VERTICAL instead, + which is a quick and easy change. But the recommendation is to switch to + #GtkGrid, since #GtkBox is going to go away eventually. + See [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. + + + 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: +|[ +<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: +|[ +<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: +|[ +<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: +|[ +<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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + Reverses the effects of gtk_widget_show(), causing the widget to be +hidden (invisible to the user). + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 useful in widget implementations. +Causes a widget to be unrealized (frees all GDK resources +associated with the widget, such as @widget->window). + + + + + + + a #GtkWidget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + position and size to be allocated to @widget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkWidget + + + + the name of a child property installed on the + class of @widget’s parent + + + + + + + + + + + + + + + + + + + + + + + + + + The #GtkSizeRequestMode preferred by @widget. + + + + + a #GtkWidget instance + + + + + + + + + + + + + + a #GtkWidget instance + + + + location to store the minimum height, or %NULL + + + + location to store the natural height, or %NULL + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + a #GtkWidget instance + + + + location to store the minimum width, or %NULL + + + + location to store the natural width, or %NULL + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if the signal has been handled + + + + + a #GtkWidget + + + + %TRUE if there are other widgets with the same mnemonic + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %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 + + + + + + + + + + return from the event signal emission (%TRUE if + the event was handled) + + + + + a #GtkWidget + + + + a #GdkEvent + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the #AtkObject associated with @widget + + + + + a #GtkWidget + + + + + + + + + + + + + + + + + + + + + + + + + + %TRUE if the accelerator can be activated. + + + + + a #GtkWidget + + + + the ID of a signal installed on @widget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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: +|[ +<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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 stuck. 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The parent class. + + + + + + + + + + + a #GtkWindow + + + + widget to be the new focus widget, or %NULL to unset + any focus widget for the toplevel window. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + 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. + + + + + 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 + + + + + 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. + + + %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. + + + %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 + + + + + diff --git a/gir-files/Gtk-4.0.gir b/gir-files/Gtk-4.0.gir new file mode 100644 index 0000000..c319dc7 --- /dev/null +++ b/gir-files/Gtk-4.0.gir @@ -0,0 +1,112822 @@ + + + + + + + + + + + + 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" --> +GdkTexture *example_logo = gdk_texture_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 paintable displayed as logo in the about dialog. + + + the paintable displayed as logo. The + paintable 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 system information that is shown in the about dialog. + + + the system information + + + + + 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 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 surface 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 #GdkPaintable, or %NULL + + + + + + Sets the surface 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 system information to be displayed in the about +dialog. If @system_information is %NULL, the system information +tab is hidden. + +See #GtkAboutdialog:system-information. + + + + + + + a #GtkAboutDialog + + + + system information or %NULL + + + + + + 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 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, 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(). + + + + Information about the system on which the program is running. +This is displayed in a separate tab, 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://. + + + + 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()). + +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 + + + + + + + + + + + + + + + + + + + + + + + + + + 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(). + + + %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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The accelerator keyval + + + + The accelerator modifiers + + + + The accelerator flags + + + + + The #GtkAccelLabel is a widget that shows an accelerator next to a description +of said accelerator, e.g. “Save Document 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_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" --> +accellabel +╰── box + ├── label + ╰── accelerator +]| + +#GtkAccelLabel has a main CSS node with the name accellabel. +It adds a subnode with name box, containing two child nodes with +name label and 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. + + + + + + Returns the current label, set via gtk_accel_label_set_label() + + + @accel_label's label + + + + + a #GtkAccelLabel + + + + + + Returns whether the accel label interprets underscores in it's +label property as mnemonic indicators. +See gtk_accel_label_set_use_underline() and gtk_label_set_use_underline(); + + + whether the accel label uses mnemonic underlines + + + + + 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 + + + + + + Sets the label part of the accel label. + + + + + + + a #GtkAccelLabel + + + + The new label text + + + + + + Controls whether to interpret underscores in the text label of @accel_label +as mnemonic indicators. See also gtk_label_set_use_underline() + + + + + + + a #GtkAccelLabel + + + + Whether to use underlines in the label or not + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Accelerator maps are used to define runtime configurable accelerators. +Functions for manipulating them are are usually used by higher level +convenience mechanisms 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. + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + Gets the value of the #GtkActionBar:revealed property. + + + the current value of the #GtkActionBar:revealed property. + + + + + 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 + + + + + + Sets the #GtkActionBar:revealed property to @revealed. Changing this will +make @action_bar reveal (%TRUE) or conceal (%FALSE) itself via a sliding +transition. + +Note: this does not show or hide @action_bar in the #GtkWidget:visible sense, +so revealing has no effect if #GtkWidget:visible is %FALSE. + + + + + + + a #GtkActionBar + + + + The new value of the property + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + the action name, or %NULL if none is set + + + + + a #GtkActionable widget + + + + + + + + + + + + + + a #GtkActionable widget + + + + an action name, or %NULL + + + + + + + + + + the current target value + + + + + a #GtkActionable widget + + + + + + + + + + + + + + a #GtkActionable widget + + + + a #GVariant to set as the target value, 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + #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 +#GtkAppChooserbutton::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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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/tree/master/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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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 + + + + + + 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 will make GTK+ track the session state (such as the +#GtkApplication::screensaver-active property). + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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://gitlab.gnome.org/GNOME/gtk/tree/master/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. + + + + + + + + + + + + + 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. + + + + 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 maintains a #GtkAssistantPage object for each added +child, which holds additional per-child properties. You +obtain the #GtkAssistantPage for a child with 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 assistant. + + + + + + Creates a new #GtkAssistant. + + + a newly created #GtkAssistant + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + Returns the #GtkAssistantPage object for @child. + + + the #GtkAssistantPage for @child + + + + + a #GtkAssistant + + + + a child of @assistant + + + + + + Gets whether @page is complete. + + + %TRUE if @page is complete. + + + + + 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 + + + + + + Gets a list model of the assistant pages. + + + A list model of the pages. + + + + + a #GtkAssistant + + + + + + 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 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the child to which @page belongs. + + + the child to which @page belongs + + + + + a #GtkAssistantPage + + + + + + + + + Setting the "complete" property to %TRUE marks a page as +complete (i.e.: all the required fields are filled out). GTK+ uses +this information to control the sensitivity of the navigation buttons. + + + + The type of the assistant page. + + + + The title of the page. + + + + + + + + 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(). + + + + + + + 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. + + + + + 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 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GtkBinLayout is a #GtkLayoutManager subclass useful for create "bins" of +widgets. GtkBinLayout will stack each child of a widget on top of each +other, using the #GtkWidget:hexpand, #GtkWidget:vexpand, #GtkWidget:halign, +and #GtkWidget:valign properties of each child to determine where they +should be positioned. + + + Creates a new #GtkBinLayout instance. + + + the newly created #GtkBinLayout + + + + + + + + + + + + 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 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. + +Use repeated calls to gtk_container_add() to pack widgets into a +GtkBox from start to end. Use gtk_container_remove() to remove widgets +from the GtkBox. gtk_box_insert_child_after() can be used to add a child +at a particular position. + +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. + +Use 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. + + + + + + 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 + + + + + + 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 + + + + + + Inserts @child in the position after @sibling in the list +of @box children. If @sibling is %NULL, insert @child at +the first position. + + + + + + + a #GtkBox + + + + the #GtkWidget to insert + + + + the sibling to move @child after, or %NULL + + + + + + Moves @child to the position after @sibling in the list +of @box children. If @sibling is %NULL, move @child to +the first position. + + + + + + + a #GtkBox + + + + the #GtkWidget to move, must be a child of @box + + + + the sibling to move @child after, or %NULL + + + + + + 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 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A GtkBoxLayout is a layout manager that arranges the children of any +widget using it into a single row or column, depending on the value +of its #GtkOrientable:orientation property. Within the other dimension +all children all allocated the same size. The GtkBoxLayout will respect +the #GtkWidget:halign and #GtkWidget:valign properties of each child +widget. + +If you want all children to be assigned the same size, you can use +the #GtkBoxLayout:homogeneous property. + +If you want to specify the amount of space placed between each child, +you can use the #GtkBoxLayout:spacing property. + + + + Creates a new box layout. + + + a new box layout + + + + + the orientation for the new layout + + + + + + 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 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 position of the allocated baseline within the extra space +allocated to each child of the widget using a box layout +manager. + +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 +homogeneously among the children of the widget using it as a +layout manager. + + + + The space between each child of the widget using the box +layout as its layout manager. + + + + + + + + + + + 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 + + + + + + + + + + + a #GtkBuildable + + + + name to set + + + + + + + + + + the name set with gtk_buildable_set_name() + + + + + a #GtkBuildable + + + + + + + + + + + + + + a #GtkBuildable + + + + a #GtkBuilder + + + + child to add + + + + kind of child or %NULL + + + + + + + + + + + + + + a #GtkBuildable + + + + a #GtkBuilder + + + + name of property + + + + value of property + + + + + + + + + + the constructed child + + + + + A #GtkBuildable + + + + #GtkBuilder used to construct this object + + + + name of child to construct + + + + + + + + + + %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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + a #GtkBuildable + + + + a #GtkBuilder + + + + child object or %NULL for non-child tags + + + + the name of the tag + + + + user data created in custom_tag_start + + + + + + + + + + + + + + a #GtkBuildable + + + + a #GtkBuilder + + + + + + + + + + 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. + +[RELAX NG Compact Syntax](https://gitlab.gnome.org/GNOME/gtk/tree/master/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 implement 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” +propery 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 + +|[ +<interface> + <object class="GtkDialog" id="dialog1"> + <child internal-child="vbox"> + <object class="GtkBox" id="vbox1"> + <child internal-child="action_area"> + <object class="GtkBox" id="hbuttonbox1"> + <child> + <object class="GtkButton" id="ok_button"> + <property name="label">gtk-ok</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(). + + + %TRUE on success, %FALSE 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(). + + + %TRUE on success, %FALSE 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 %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 [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. + + + %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 [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. + + + %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 [GtkBuilder UI definition][BUILDER-UI] +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 + + + + + + + + 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 or %NULL + in case it was never set or explicitly unset via gtk_builder_set_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, #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, .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. + + + a new #GtkButton displaying the themed icon + + + + + an icon name or %NULL + + + + + + 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 + + + + + + + + + + + + + + + + + Emits a #GtkButton::clicked signal to the given #GtkButton. + + + + + + + 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. + + + + + + Returns the icon name set via gtk_button_set_icon_name(). + + + The icon name set via gtk_button_set_icon_name() + + + + + 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 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 + + + + + + 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 + + + + A 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 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 #GtkButton you want to set relief styles of + + + + The GtkReliefStyle as described above + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + 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). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The parent class. + + + + + + + + + + + The #GtkButton you want to send the signal to. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Snapshots @area’s cells according to @area’s layout onto at +the given coordinates. + + + + + + + a #GtkCellArea + + + + the #GtkCellAreaContext 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 #GtkCellRendererState 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 #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 + + + + + + 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 + + + + + + Snapshots @area’s cells according to @area’s layout onto at +the given coordinates. + + + + + + + a #GtkCellArea + + + + the #GtkCellAreaContext 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 #GtkCellRendererState 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 + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkCellArea + + + + the #GtkCellRenderer to add to @area + + + + + + + + + + + + + + a #GtkCellArea + + + + the #GtkCellRenderer to remove from @area + + + + + + + + + + + + + + a #GtkCellArea + + + + the #GtkCellCallback to call + + + + user provided data pointer + + + + + + + + + + + + + + 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 + + + + + + + + + + %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. + + + + + + + + + + + + + + a #GtkCellArea + + + + the #GtkCellAreaContext 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 #GtkCellRendererState for @area in this row. + + + + whether @area should paint focus on focused cells for focused rows or not. + + + + + + + + + + + + + + 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 + + + + + + + + + + a newly created #GtkCellAreaContext which can be used with @area. + + + + + a #GtkCellArea + + + + + + + + + + a newly created #GtkCellAreaContext copy of @context. + + + + + a #GtkCellArea + + + + the #GtkCellAreaContext to copy + + + + + + + + + + The #GtkSizeRequestMode preferred by @area. + + + + + a #GtkCellArea + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %TRUE if focus remains inside @area as a result of this call. + + + + + a #GtkCellArea + + + + the #GtkDirectionType + + + + + + + + + + whether @area can do anything when activated. + + + + + a #GtkCellArea + + + + + + + + + + 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. + + + + + + + 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(). + + + + + + + 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. + + + + + + + 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(). + + + + + + + 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(). + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + a #GtkCellAreaContext + + + + + + + + + + + + + + a #GtkCellAreaContext + + + + a proposed width for allocation + + + + location to store the minimum height, + or %NULL + + + + location to store the natural height, + or %NULL + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + A #GtkCellEditable + + + + + + + + + + + + + + A #GtkCellEditable + + + + + + + + + + + + + + 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: +|[ +<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: + +|[ +<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() + + + + + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer + + + + %TRUE if @cell is to be given extra space allocated to @cell_layout + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer + + + + %TRUE if @cell is to be given extra space allocated to @cell_layout + + + + + + + + + + + + + + a #GtkCellLayout + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer + + + + an attribute on the renderer + + + + the column position on the model to get the attribute from + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer + + + + the #GtkCellLayoutDataFunc to use, or %NULL + + + + user data for @func + + + + destroy notify for @func_data + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer to clear the attribute mapping on + + + + + + + + + + + + + + a #GtkCellLayout + + + + a #GtkCellRenderer to reorder + + + + new position to insert @cell at + + + + + + + + + + + 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 + + + + + + + + + + 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_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 #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #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 + + + + + + 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 + + + + + + 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 + + + + + + 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 #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 #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 + + + + + + + + + + + + + + + The #GtkSizeRequestMode preferred by this renderer. + + + + + a #GtkCellRenderer instance + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + %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 + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 + + + The cell is in a row that is expanded + + + + 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 #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 #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 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 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 #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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The GtkCenterBox widget arranges three children in a horizontal +or vertical arrangement, keeping the middle child centered as well +as possible. + +To add children to GtkCenterBox, use gtk_center_box_set_start_widget(), +gtk_center_box_set_center_widget() and gtk_center_box_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. + + + + + + Creates a new #GtkCenterBox. + + + the new #GtkCenterBox. + + + + + Gets the value set by gtk_center_box_set_baseline_position(). + + + the baseline position + + + + + a #GtkCenterBox + + + + + + Gets the center widget, or %NULL if there is none. + + + the center widget. + + + + + a #GtkCenterBox + + + + + + Gets the end widget, or %NULL if there is none. + + + the end widget. + + + + + a #GtkCenterBox + + + + + + Gets the start widget, or %NULL if there is none. + + + the start widget. + + + + + a #GtkCenterBox + + + + + + 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 wrt. the extra space +available. + + + + + + + a #GtkCenterBox + + + + a #GtkBaselinePosition + + + + + + Sets the center widget. To remove the existing center widget, pas %NULL. + + + + + + + a #GtkCenterBox + + + + the new center widget, or %NULL + + + + + + Sets the end widget. To remove the existing end widget, pass %NULL. + + + + + + + a #GtkCenterBox + + + + the new end widget, or %NULL + + + + + + Sets the start widget. To remove the existing start widget, pass %NULL. + + + + + + + a #GtkCenterBox + + + + the new start widget, or %NULL + + + + + + + + + + + + + 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_check_button_set_draw_indicator()) 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 + + + + + + Returns Whether or not the indicator part of the button gets drawn. + + + The value of the GtkCheckButton:draw-indicator property. + + + + + a #GtkCheckButton + + + + + + Returns whether the check button is in an inconsistent state. + + + %TRUE if @check_button is currently in an 'in between' state, %FALSE otherwise. + + + + + a #GtkCheckButton + + + + + + Sets whether the indicator part of the button is drawn. This is important for +cases where the check button should have the functinality of a check button, +but the visuals of a regular button, like in a #GtkStackSwitcher. + + + + + + + a #GtkCheckButton + + + + Whether or not to draw the indicator part of the button + + + + + + If 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, you may want to +display the toggle in an "in between" state. Normally you would +turn off the inconsistent state again if the user checks the +check button. This has to be done manually, +gtk_check_button_set_inconsistent only affects visual appearance, +not the semantics of the button. + + + + + + + a #GtkCheckButton + + + + %TRUE if state is inconsistent + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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. + + + + + + + + + + + a #GtkCheckMenuItem. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + a new color button + + + + + A #GdkRGBA to set the current color with + + + + + + + + + + + + + + + + + Gets the title of the color selection dialog. + + + An internal string, do not free the return value + + + + + a #GtkColorButton + + + + + + Sets the title for the color selection dialog. + + + + + + + a #GtkColorButton + + + + String containing new window title + + + + + + 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_chooser_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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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 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 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 + + + + + + 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 of @combo_box. Note that currently this does not do anything +with the device, as it was previously only used for list-mode ComboBoxes, +and those were removed in GTK+ 4. However, it is retained in case similar +functionality is added back later. + + + + + + + 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 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 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 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 + + + + + + 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. + + + + Whether the dropdown button is sensitive when +the model is empty. + + + + 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. + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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: +|[ +<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 horizontal #GtkBox 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 + + + + + Adds @widget to @container. Typically used for simple containers +such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated +layout containers such #GtkGrid, this function will +pick default packing parameters that may not be correct. So +consider functions such as 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 + + + + + + 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 + + + + + + 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 + + + + + + + + + + + + + + + + + + + + Adds @widget to @container. Typically used for simple containers +such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated +layout containers such #GtkGrid, this function will +pick default packing parameters that may not be correct. So +consider functions such as 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 + + + + + + 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 + + + + + + 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 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 + + + + + + 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 + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Get a list of children. + + + + + + + + + the container + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Base class for containers. + + + The parent class. + + + + + + + + + + + a #GtkContainer + + + + a widget to be placed inside @container + + + + + + + + + + + + + + a #GtkContainer + + + + a current child of @container + + + + + + + + + + + + + + a #GtkContainer + + + + a callback + + + + callback user data + + + + + + + + + + + + + + + + + + + + + + + + + + a #GType + + + + + a #GtkContainer + + + + + + + + + + A newly created #GtkWidgetPath + + + + + a #GtkContainer + + + + a child of @container + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + @GtkCssLocation is used to present a location in a file - or other +source of data parsed by the CSS engine. + +The @bytes and @line_bytes offsets are meant to be used to +programmatically match data. The @lines and @line_chars offsets +can be used for printing the location in a file. + +Note that the @lines parameter starts from 0 and is increased +whenever a CSS line break is encountered. (CSS defines the C character +sequences "\r\n", "\r", "\n" and "\f" as newlines.) +If your document uses different rules for line breaking, you might want +run into problems here. + + + number of bytes parsed since the beginning + + + + number of characters parsed since the beginning + + + + number of full lines that have been parsed + If you want to display this as a line number, you + need to add 1 to this. + + + + Number of bytes parsed since the last line break + + + + Number of characters parsed since the last line + break + + + + + 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_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 #GtkSettings:gtk-theme-name setting), +VARIANT is the variant to load (see the #GtkSettings: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. + + + + Returns a newly created #GtkCssProvider. + + + A new #GtkCssProvider + + + + + + + + + + + + + + + + + + + + + + Loads @data into @css_provider, and by doing so clears any previously loaded +information. + + + + + + + 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. + + + + + + + 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. + + + + + + + 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 + + + + + + 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. + + + + + + + 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 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + 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 + + + + + + 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 +@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 + + + + + + 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. + + + @section itself. + + + + + a #GtkCssSection + + + + + + Prints the section into a human-readable text form using +gtk_css_section_print(). + + + A new string. + + + + + a #GtkCssSection + + + + + + Decrements the reference count on @section, freeing the +structure if the reference count reaches 0. + + + + + + + a #GtkCssSection + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 formats + 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 formats 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 gdk_drag_finish(). If + the action was a move, then if the drag was successful, then %TRUE will be + passed for the @delete parameter to gdk_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 +#GtkBox, 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. + +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 (dialog); +} +]| + +# GtkDialog as GtkBuildable + +The GtkDialog implementation of the #GtkBuildable interface exposes the +@content_area and @action_area as internal children with the names +“content_area” 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: +|[ +<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> +]| + + + + + + Creates a new dialog box. + +Widgets should not be packed into this #GtkWindow +directly, but into the @content_area 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 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. 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 + + + + + + + + + + + + + + + + + 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 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 delete events +is disabled; if the dialog receives a 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 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. + + + + + + + + + + + a #GtkDialog + + + + response ID + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + 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: + +- 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. + +- Call gtk_drawing_area_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 + +|[<!-- language="C" --> +void +draw_function (GtkDrawingArea *area, cairo_t *cr, + int width, int height, + gpointer data) +{ + GdkRGBA color; + GtkStyleContext *context; + + context = gtk_widget_get_style_context (GTK_WIDGET (area)); + + cairo_arc (cr, + width / 2.0, height / 2.0, + MIN (width, height) / 2.0, + 0, 2 * G_PI); + + gtk_style_context_get_color (context, + &color); + gdk_cairo_set_source_rgba (cr, &color); + + cairo_fill (cr); +} + +void 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); + +} +]| + +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 gtk_widget_queue_draw_region(), +gtk_widget_queue_draw_area() or gtk_widget_queue_draw(). +This will cause the drawing area to call the draw function again. + +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. + +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 value previously set via gtk_drawing_area_set_content_height(). + + + The height requested for content of the drawing area + + + + + a #GtkDrawingArea + + + + + + Retrieves the value previously set via gtk_drawing_area_set_content_width(). + + + 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 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 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. It 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 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. See gtk_drawing_area_set_content_height() for details. + + + + The content width. See gtk_drawing_area_set_content_width() for details. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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 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 gtk_editable_install_properties(), +passing the first available property ID: + +|[ +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: + +|[ +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 get_delegate() vfunc returns. + +In your instance_init function, create your text widget, and then call +gtk_editable_init_delegate(): + +|[ +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 gtk_editable_finish_delegate() before +destroying your text widget: + +|[ +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 gtk_editable_delegate_set_property() in your set_property +function (and similar for get_property), to set the editable properties: + +|[ + ... + if (gtk_editable_delegate_set_property (object, prop_id, value, pspec)) + return; + + switch (prop_id) + ... +]| + + + + Gets a property of the #GtkEditable delegate for @object. + +This is helper function that should be called in get_property, +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 set_property, +before handling your own properties. + + + %TRUE if the property was found + + + + + a #GObject + + + + a property ID + + + + value to set + + + + the #GParamSpec for the property + + + + + + Installs the GtkEditable properties for @class. + +This is a helper function that should be called in class_init, +after installing your own properties. + +To handle the properties in your set_property and get_property +functions, you can either use gtk_editable_delegate_set_property() +and 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 +#GtkEditableProperties 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 append + + + + the length of the text in bytes, or -1 + + + + location of the position text will be inserted at + + + + + + + + + + + + + + + + + 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, or %NULL + + + + location to store the end position, or %NULL + + + + + + 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 append + + + + 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 + + + + + + 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 gtk_editable_init_delegate(). + +This is a helper function that should be called from dispose, +before removing the delegate object. + + + + + + + a #GtkEditable + + + + + + Gets the value set by gtk_editable_set_alignment(). + + + 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 + + + + + + Retrieves whether @editable is editable. +See gtk_editable_set_editable(). + + + %TRUE if @editable is editable. + + + + + a #GtkEditable + + + + + + Retrieves the desired maximum width of @editable, in characters. +See gtk_editable_set_max_width_chars(). + + + 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, or %NULL + + + + location to store the end position, or %NULL + + + + + + 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 value set by gtk_editable_set_width_chars(). + + + number of chars to request space for, or negative if unset + + + + + a #GtkEditable + + + + + + Sets up a delegate for #GtkEditable, 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 append + + + + 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 or not. + + + + + + + a #GtkEditable + + + + %TRUE if the user is allowed to edit the text + in the widget + + + + + + 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, +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 ::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 pointer to the contents of the editable. + + + + + a #GtkEditable + + + + + + + + + + + + + + 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 + + + + + + + + + + %TRUE if there is a non-empty selection, %FALSE otherwise + + + + + a #GtkEditable + + + + location to store the starting position, or %NULL + + + + location to store the end position, or %NULL + + + + + + + + + + + + + + a #GtkEditable + + + + start of region + + + + end of region + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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(). + +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 an icon name or a +paintable. 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[.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 #GtkText. + + + + + + + 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. + + + + + + + + + + + + + + + + + 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 + + + + + + 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 #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, relative to @entry + + + + the y coordinate of the position to find, relative to @entry + + + + + + 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 +paintable 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 +paintable 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 #GdkPaintable used for the icon. + +If no #GdkPaintable was used for the icon, %NULL is returned. + + + A #GdkPaintable, or %NULL 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, 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 + + + + + + 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 + + + + + + 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 + + + + + + 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. 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 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 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 + + + + + + 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 + + + + + + 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. + + + + + + + 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 + + + + + + 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 #GdkPaintable + +If @paintable is %NULL, no icon will be shown in the specified position. + + + + + + + a #GtkEntry + + + + Icon position + + + + A #GdkPaintable, 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 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 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, 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 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 + + + + + + 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. + + + + + + + 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. + + + + 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. + + + + + + + Whether the invisible char has been set for the #GtkEntry. + + + + + + + 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 #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 +#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 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. + + + + 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 +#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 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(). + + + + + + + + + + The length of the text in the #GtkEntry. + + + + When %TRUE, pasted multi-line text is truncated to the first line. + + + + + + + + + + + + + + + The ::icon-press signal is emitted when an activatable icon +is clicked. + + + + + + The position of the clicked icon + + + + + + 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 #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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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_editable_get_text (GTK_EDITABLE (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). + + + + + + + #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 gtk_event_controll_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. + + + 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 +#GtkEventControllerKey::key-pressed, +#GtkEventControllerKey::key-released +or +#GtkEventControllerKey::modifiers +signals. + + + whether the @widget handled the event + + + + + a #GtkEventControllerKey + + + + a #GtkWidget + + + + + + Returns the widget that was holding focus before. + +This function can only be used in handlers for the +#GtkEventControllerKey::focus-in and +#GtkEventControllerKey::focus-out signals. + + + the previous focus + + + + + a #GtkEventControllerKey + + + + + + Returns the widget that will be holding focus afterwards. + +This function can only be used in handlers for the +#GtkEventControllerKey::focus-in and +#GtkEventControllerKey::focus-out signals. + + + the next focus + + + + + a #GtkEventControllerKey + + + + + + Gets the key group of the current event of this @controller. +See gdk_event_get_key_group(). + + + 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 + + + + + + Whether focus is in a descendant of the controllers widget. +See #GtkEventControllerKey:is-focus. + +When handling focus events, this property is updated +before #GtkEventControllerKey::focus-in or +#GtkEventControllerKey::focus-out are emitted. + + + + Whether focus is in the controllers widget itself, +as opposed to in a descendent widget. See +#GtkEventControllerKey:contains-focus. + +When handling focus events, this property is updated +before #GtkEventControllerKey::focus-in or +#GtkEventControllerKey::focus-out are emitted. + + + + This signal is emitted whenever the widget controlled +by the @controller or one of its descendants) is given +the keyboard focus. + + + + + + crossing mode indicating what caused this change + + + + detail indication where the focus is coming from + + + + + + This signal is emitted whenever the widget controlled +by the @controller (or one of its descendants) loses +the keyboard focus. + + + + + + crossing mode indicating what caused this change + + + + detail indication where the focus is going + + + + + + This signal is emitted whenever the input method context filters away a +keypress and prevents the @controller receiving it. See +gtk_event_controller_key_set_im_context() and +gtk_im_context_filter_keypress(). + + + + + + 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. + + + + + + This signal is emitted whenever the state of modifier keys and pointer +buttons change. + + + + + + the released key. + + + + + + + + + + #GtkEventControllerLegacy is an event controller that gives you +direct 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 + + + + + + + + + + #GtkEventControllerMotion is an event controller meant for situations +where you need to track the position of the pointer. + + + Creates a new event controller that will handle motion events. + + + a new #GtkEventControllerMotion + + + + + Returns the widget that contained the pointer before. + +This function can only be used in handlers for the +#GtkEventControllerMotion::enter and +#GtkEventControllerMotion::leave signals. + + + the previous pointer focus + + + + + a #GtkEventControllerMotion + + + + + + Returns the widget that will contain the pointer afterwards. + +This function can only be used in handlers for the +#GtkEventControllerMotion::enter and +#GtkEventControllerMotion::leave signals. + + + the next pointer focus + + + + + a #GtkEventControllerMotion + + + + + + Whether the pointer is in a descendant of the controllers widget. +See #GtkEventControllerMotion:is-pointer-focus. + +When handling crossing events, this property is updated +before #GtkEventControllerMotion::enter or +#GtkEventControllerMotion::leave are emitted. + + + + Whether the pointer is in the controllers widget itself, +as opposed to in a descendent widget. See +#GtkEventControllerMotion:contains-pointer-focus. + +When handling crossing events, this property is updated +before #GtkEventControllerMotion::enter or +#GtkEventControllerMotion::leave are emitted. + + + + Signals that the pointer has entered the widget. + + + + + + the x coordinate + + + + the y coordinate + + + + the crossing mode of this event + + + + the kind of crossing event + + + + + + Signals that pointer has left the widget. + + + + + + the crossing mode of this event + + + + the kind of crossing event + + + + + + 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. + + + Creates a new event controller that will handle scroll events. + + + a new #GtkEventControllerScroll + + + + + 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. + + %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 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 a 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: +|[ +<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 +╰── box + ├── 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 + + + + + + + + + + + + + + + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + 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 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 + + + + + + + + + + + + + + + When this property is %TRUE, the expander will resize the toplevel +widget containing the expander upon expanding and collapsing. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The parent class. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 open() or 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 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 standard 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 is %FALSE), +then the selected file or files are guaranteed to be +accessible through the operating system’s 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 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 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 standard 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 standard 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. + + + + + + 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 + + + + + + + + + + + + + + + + + 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. + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 predefined +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 +[predefined 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 + + + + 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 #GtkFileChooserNative + + + + + + 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 #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 activates the button. + + + + + + + a #GtkFileChooserNative + + + + 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 #GtkFileChooserNative + + + + 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: +|[ +<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 + + + + + #GtkFilterListModel is a list model that filters a given other +listmodel. +It hides some elements from the other model according to +criteria given by a #GtkFilterListModelFilterFunc. + + + + Creates a new #GtkFilterListModel that will filter @model using the given +@filter_func. + + + a new #GtkFilterListModel + + + + + the model to sort + + + + filter function or %NULL to not filter items + + + + user data passed to @filter_func + + + + destroy notifier for @user_data + + + + + + Creates a new empty filter list model set up to return items of type @item_type. +It is up to the application to set a proper filter function and model to ensure +the item type is matched. + + + a new #GtkFilterListModel + + + + + the type of the items that will be returned + + + + + + Gets the model currently filtered or %NULL if none. + + + The model that gets filtered + + + + + a #GtkFilterListModel + + + + + + Checks if a filter function is currently set on @self + + + %TRUE if a filter function is set + + + + + a #GtkFilterListModel + + + + + + Causes @self to refilter all items in the model. + +Calling this function is necessary when data used by the filter +function has changed. + + + + + + + a #GtkFilterListModel + + + + + + Sets the function used to filter items. The function will be called for every +item and if it returns %TRUE the item is considered visible. + + + + + + + a #GtkFilterListModel + + + + filter function or %NULL to not filter items + + + + user data passed to @filter_func + + + + destroy notifier for @user_data + + + + + + 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 function to ensure +that item types match. + + + + + + + a #GtkFilterListModel + + + + The model to be filtered + + + + + + If a filter is set for this model + + + + The #GType for elements of this object + + + + The model being filtered + + + + + + + + + + + User function that is called to determine if the @item of the original model should be visible. +If it should be visible, this function must return %TRUE. If the model should filter out the +@item, %FALSE must be returned. + + + %TRUE to keep the item around + + + + + The item that may be filtered + + + + user data + + + + + + 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. + + + + + Creates a new #GtkFixed. + + + a new #GtkFixed. + + + + + Retrieves the translation transformation of the given child #GtkWidget +in the given #GtkFixed container. + +See also: 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 given #GtkFixed container. + + + + + + + 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 and assigns a translation +transformation to the given @x and @y coordinates to it. + + + + + + + a #GtkFixed. + + + + the widget to add. + + + + the horizontal position to place the widget at. + + + + the vertical position to place the widget at. + + + + + + Sets the transformation for @widget. + +This is a convenience function that retrieves the #GtkFixedLayoutChild +instance associated to @widget and calls gtk_fixed_layout_child_set_position(). + + + + + + + a #GtkFixed + + + + a #GtkWidget, child of @fixed + + + + the transformation assigned to @widget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GtkFixedLayout is a layout manager which can place child widgets +at fixed positions, and with fixed sizes. + +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 GUI +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 + + + + + + + + Retrieves the transformation of the child of a #GtkFixedLayout. + + + a #GskTransform + + + + + a #GtkFixedLayoutChild + + + + + + Sets the transformation of the child of a #GtkFixedLayout. + + + + + + + a #GtkFixedLayoutChild + + + + a #GskTransform + + + + + + + + + + + + + + + + + + + + + + #GtkFlattenListModel is a list model that takes a list model containing +list models and flattens it into a single model. + +Another term for this is concatenation: #GtkFlattenListModel takes a +list of lists and concatenates them into a single list. + + + + Creates a new #GtkFlattenListModel that flattens @list. The +models returned by @model must conform to the given @item_type, +either by having an identical type or a subtype. + + + a new #GtkFlattenListModel + + + + + The type of items in the to-be-flattened models + + + + the item to be flattened + + + + + + Gets the model set via gtk_flatten_list_model_set_model(). + + + The model flattened by @self + + + + + a #GtkFlattenListModel + + + + + + Sets a new model to be flattened. The model must contain items of +#GtkListModel that conform to the item type of @self. + + + + + + + a #GtkFlattenListModel + + + + the new model or %NULL + + + + + + The #GTpe for elements of this object + + + + The model being flattened + + + + + + + + + + + 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. 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 (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 fontbutton. + + + + + + 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 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 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 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 changing OpenType font variation axes + + + 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() + + + + + + The frame widget is a bin that surrounds its child with a decorative +frame and an optional label. If present, the label is drawn inside +the top edge of the frame. The horizontal 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: +|[ +<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[.flat] +├── <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. + +The 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 alignment of the frame’s label. See +gtk_frame_set_label_align(). + + + + + + + a #GtkFrame + + + + + + 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 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 #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 main CSS node, frame. + + + + + + + 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" --> + +]| + +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; + } + + 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 #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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_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 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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::event signal. +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 #GdkSurfaces +- 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 + + + + + + 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 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 + + + + + + Separates @gesture into an isolated group. + + + + + + + a #GtkGesture + + + + + + The number of touch points that trigger recognition on this gesture, + + + + 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 + + + + + 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 + + + + + + + + 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 + + + + + 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. + + + + + + This signal is 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 + + + + + + + + + + #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 + + + + + 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 + + + + + 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 + + + + + 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 + + + + + + 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 +#GtkGestureStylus:motion signal. + +This function may only be called within a #GtkGestureStylus::motion +signal handler, the state given in this signal and obtainable through +gtk_gesture_stylus_get_axis() call express the latest (most up-to-date) +state in motion history. + +@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 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 + + + + + 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 + + + + + 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 + + + + + + + + + + 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 + + + + + + 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 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GtkGridLayout is a layout manager which arranges child widgets in +rows and columns, with arbitrary positions and horizontal/vertical +spans. + +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 #GtkGridLayoutChild associated to each child widget. + +The behaviour of GtkGrid 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 as set by +gtk_grid_layout_set_row_baseline_position(), or the default value +of %GTK_BASELINE_POSITION_CENTER. + + + 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. + + + + + Layout properties for children of #GtkGridLayout. + + + Retrieves the number of columns that @child spans to. + + + the number of columns + + + + + a #GtkGridLayoutChild + + + + + + Retrieves the column number to which @child attaches its left side. + + + the column number + + + + + a #GtkGridLayoutChild + + + + + + Retrieves the number of rows that @child spans to. + + + the number of row + + + + + a #GtkGridLayoutChild + + + + + + Retrieves the row number to which @child attaches its top side. + + + the row number + + + + + a #GtkGridLayoutChild + + + + + + Sets the number of columns @child spans to. + + + + + + + a #GtkGridLayoutChild + + + + the span of @child + + + + + + Sets the column number to attach the left side of @child. + + + + + + + a #GtkGridLayoutChild + + + + the attach point for @child + + + + + + Sets the number of rows @child spans to. + + + + + + + a #GtkGridLayoutChild + + + + the span of @child + + + + + + Sets the row number to attach the top side of @child. + + + + + + + a #GtkGridLayoutChild + + + + the attach point for @child + + + + + + The number of columns the child spans to. + + + + The column number to attach the left side of the child to. + + + + The number of rows the child spans to. + + + + The row number to attach the top side of the child to. + + + + + + + + + + + + + + + + + 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 +title buttons. + + + %TRUE if title buttons 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 +title buttons including close, maximize, and minimize. + + + + + + + a #GtkHeaderBar + + + + %TRUE to show standard title buttons + + + + + + 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 title buttons like close, minimize, maximize. + +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. + + + + + + + + + + + + + + + + + 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 +#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 +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 +#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 +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %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. + + + + + + + + + + + + + + a #GtkIMContext + + + + the client widget. This may be %NULL to indicate + that the previous client widget no longer exists. + + + + + + + + + + + + + + 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. + + + + + + + + + + %TRUE if the input method handled the key event. + + + + + a #GtkIMContext + + + + the key event + + + + + + + + + + + + + + a #GtkIMContext + + + + + + + + + + + + + + a #GtkIMContext + + + + + + + + + + + + + + a #GtkIMContext + + + + + + + + + + + + + + a #GtkIMContext + + + + new location + + + + + + + + + + + + + + a #GtkIMContext + + + + whether the IM context should use the preedit string. + + + + + + + + + + + + + + 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. + + + + + + + + + + %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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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-4.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 + (cannot be greater than #GTK_MAX_COMPOSE_LEN) + + + + number of sequences in the table + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #GtkIMMulticontext. + + + a new #GtkIMMulticontext. + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + 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 + + + + + + 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 monitor 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; +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 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 + + + + + + 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 foreground 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. + + + + + + Returns a texture object that can be used to render the icon +with GSK. + + + the icon texture; this may be a newly + created texture or a new reference to an exiting texture. Use + g_object_unref() to release your reference. + + + + + a #GtkIconInfo + + + + + + + + + + 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() + + + Always get the icon scaled to the + requested size + + + 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 + + + Try to load a variant of the icon for left-to-right + text direction + + + Try to load a variant of the icon for right-to-left + text direction + + + + 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 + + + + #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. + +In many cases, named themes are used indirectly, via #GtkImage +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 #GdkDisplay +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_display() rather than creating +a new icon theme object for scratch. + + + the newly created #GtkIconTheme object. + + + + + Gets the icon theme for the default display. See +gtk_icon_theme_get_for_display(). + + + A unique #GtkIconTheme associated with + the default 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. + + + + + 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 than gtk_icon_theme_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. + +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 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_surface_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_surface_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_display(). + + + + + + + a #GtkIconTheme + + + + name of icon theme to use instead of + configured theme, or %NULL to unset a previously set custom theme + + + + + + Sets the display for an icon theme; the display is used +to track the user’s currently configured icon theme, +which might be different for different displays. + + + + + + + a #GtkIconTheme + + + + a #GdkDisplay + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + 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 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. + + + + + + + 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(). + + + %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 + + + + + + + + %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 + + + + + + + + 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. + + + 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 +#GdkTexture 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_texture_new_from_file(), then create the #GtkImage with +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 for details. +In this case, the #GtkImage:resource, gtk_image_new_from_resource() and +gtk_image_set_from_resource() should be used. + +# 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 #GtkImage:icon-size +property. + + + + + 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 +gdk_texture_new_from_file() to load the file yourself, then create +the #GtkImage from the texture. + +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. + +Note: Before 3.94, this function was taking an extra icon size +argument. See gtk_image_set_icon_size() for another way to set +the icon size. + + + 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. + +Note: Before 3.94, this function was taking an extra icon size +argument. See gtk_image_set_icon_size() for another way to set +the icon size. + + + a new #GtkImage displaying the themed icon + + + + + an icon name or %NULL + + + + + + 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. + + + a new #GtkImage + + + + + a #GdkPaintable, or %NULL + + + + + + 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 gtk_image_new_from_texture(), 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 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 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. + +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 + + + + + + Resets the image to be 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. + +Note: This function was changed in 3.94 not to use out parameters +anymore, but return the GIcon directly. See gtk_image_get_icon_size() +for a way to get the icon size. + + + a #GIcon, or %NULL + + + + + 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 gtk_image_get_storage_type()). +The returned string is owned by the #GtkImage and should not +be freed. + +Note: This function was changed in 3.94 not to use out parameters +anymore, but return the icon name directly. See gtk_image_get_icon_size() +for a way to get the icon size. + + + the icon name, or %NULL + + + + + 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 gtk_image_get_storage_type()). +The caller of this function does not own a reference to the +returned paintable. + + + the displayed paintable, 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 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 + + + + + + See gtk_image_new_from_file() for details. + + + + + + + a #GtkImage + + + + a filename or %NULL + + + + + + See gtk_image_new_from_gicon() for details. + +Note: Before 3.94, this function was taking an extra icon size +argument. See gtk_image_set_icon_size() for another way to set +the icon size. + + + + + + + a #GtkImage + + + + an icon + + + + + + See gtk_image_new_from_icon_name() for details. + +Note: Before 3.94, this function was taking an extra icon size +argument. See gtk_image_set_icon_size() for another way to set +the icon size. + + + + + + + a #GtkImage + + + + an icon name or %NULL + + + + + + See gtk_image_new_from_paintable() for details. + + + + + + + a #GtkImage + + + + a #GdkPaintable or %NULL + + + + + + See gtk_image_new_from_pixbuf() for details. + +Note: This is a helper for gtk_image_set_from_paintable(), and you can't +get back the exact pixbuf once this is called, only a paintable. + + + + + + + a #GtkImage + + + + a #GdkPixbuf or %NULL + + + + + + See gtk_image_new_from_resource() for details. + + + + + + + a #GtkImage + + + + a resource path or %NULL + + + + + + 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 +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. + + + + + + + + + + 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. + + + + + + + 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 #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_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. + 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 #GdkPaintable. + This image type was added in GTK+ 3.96 + + + + #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 (); + +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. +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 + + + + + ext 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 + + + + 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 + + + + + + Returns whether the info bar is currently revealed. + + + 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. Changing this will make +@info_bar reveal (%TRUE) or conceal (%FALSE) itself via a sliding transition. + +Note: this does not show or hide @info_bar in the #GtkWidget:visible sense, +so revealing has no effect if #GtkWidget: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 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_info_bar_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 + + + Suggest offering Emoji support + + + Suggest not offering Emoji support + + + + 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 + + + + 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. + + + + 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: +|[ +<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 + +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“, “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 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 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 or %NULL if there is none. + 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. 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 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 = "..."; +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 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GtkLayoutChild is 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. + + + + + + + + + + + + + + Layout managers are delegate classes that handle the preferred size +and the allocation of a container 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 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 #GtkLayoutChild +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 gtk_layout_manager_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: + +|[<!-- language="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 #GtkLayoutChild:layout-manager and #GtkLayoutChild: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 +gtk_layout_manager_get_layout_child() every time it needs to query the +layout properties; each #GtkLayoutChild instance should call +gtk_layout_manager_layout_changed() every time a property is updated, in +order to queue a new size measuring and allocation. + + + This function 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Measures the size of the @widget using @manager, for the +given @orientation and size. + +See [GtkWidget's geometry management section][geometry-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 + + + + + + This function 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 [GtkWidget's geometry management section][geometry-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 #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 #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + 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 + + + + 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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A GtkListBox is a vertical container that 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 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. + +# CSS nodes + +|[<!-- language="plain" --> +list[.separators] +╰── row[.activatable] +]| + +GtkListBox uses a single CSS node named list. It may carry the .separators style +class, when the #GtkListBox::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. + + + + + Creates a new #GtkListBox container. + + + a new #GtkListBox + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Select all children of @box, if the selection mode allows it. + + + + + + + a #GtkListBox + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + Returns whether the list box should show separators +between rows. + + + %TRUE if the list box shows separators + + + + + 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 + + + + + + Sets whether the list box should show separators +between rows. + + + + + + + a #GtkListBox + + + + %TRUE to show separators + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkListBox + + + + + + + + + + + + + + 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. + + + 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 +#GdkTextures 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="C" --> +<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_TEXTURE);` will create a new #GtkListStore with three columns, of type +int, string and #GdkTexture, 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. + + + + + #GtkMapListModel is a list model that takes a list model and maps the items +in that model to different items according to a #GtkMapListModelMapFunc. + +FIXME: Add useful examples here, like turning #GFile into #GFileInfo or #GdkPixmap. + +#GtkMapListModel will attempt to discard the mapped objects as soon as they are no +longer needed and recreate them if necessary. + + + + Creates a new #GtkMapListModel for the given arguments. + + + a new #GtkMapListModel + + + + + the #GType to use as the model's item type + + + + The model to map or %NULL for none + + + + map function or %NULL to not map items + + + + user data passed to @map_func + + + + destroy notifier for @user_data + + + + + + Gets the model that is curently 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 or %NULL to not map items + + + + 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 #GType for elements of this object + + + + The model being mapped + + + + + + + + + + + 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. + This function may not return %NULL + + + + + The item to map + + + + user data + + + + + + GtkMediaControls is a widget to show controls for a #GtkMediaStream +and giving users a way to use it. + + + + + Creates a new #GtkMediaControls managing the @stream passed to it. + + + a new #GtkMediaControls + + + + + a #GtkMediaStream to + manage or %NULL for none. + + + + + + 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, or %NULL + + + + + + The media-stream managed by this object or %NULL if none. + + + + + + + + + + + #GtkMediaFile is the implementation for media file usage with #GtkMediaStream. + +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 implementations using GStreamer and ffmpeg. + + + + 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 + + + + + + This is a utility function that converts the given @filename +to a #GFile and calls gtk_media_file_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 + + + + + + This is a utility function that converts the given @resource +to a #GFile and calls gtk_media_file_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 or %NULL if not + playing from a 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 or %NULL if not + playing from a stream. + + + + + a #GtkMediaFile + + + + + + If any file is still playing, stop playing it. + +Then start playing the given @file. + + + + + + + a #GtkMediaFile + + + + the file to play + + + + + + This is a utility function that converts the given @filename +to a #GFile and calls gtk_media_file_set_file(). + + + + + + + a #GtkMediaFile + + + + name of file to play + + + + + + If anything is still playing, stop playing it. Then start +playing the given @stream. + +Full control about the @stream is assumed for the duration of +playback. The stream will not bt be closed. + + + + + + + a #GtkMediaFile + + + + the stream to play from + + + + + + This is a utility function that converts the given @resource_path +to a #GFile and calls gtk_media_file_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, like when playing a file. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #GtkMediaStream is the integration point for media playback inside GTK. + +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: +gtk_media_stream_prepared(), +gtk_media_stream_unprepared(), +gtk_media_stream_update(), +gtk_media_stream_ended(), +gtk_media_stream_seek_success(), +gtk_media_stream_seek_failed(), +gtk_media_stream_gerror(), +gtk_media_stream_error(), +gtk_media_stream_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 +#GdkGLContexts or sync to the #GdkFrameClock. + +Whoever calls this function is responsible for calling +gtk_media_stream_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 gtk_media_stream_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 GtkMediaStream:seeking property will be set. + +When calling gtk_media_stream_seek() during an ongoing seek operation, +the new seek wil override any pending seek. + + + + + + + a #GtkMediaStream + + + + timestamp to seek to. + + + + + + Undoes a previous call to gtk_media_stream_realize() and 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 GtkMediaStream.play() may still happen. + + + + + + + a #GtkMediaStream + + + + + + Sets @self into an error state using a printf()-style format string. + +This is a utility function that calls gtk_media_stream_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 gtk_media_stream_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 gtk_media_stream_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. +FIXME: Or do we want to set the new error? + +To unset an error, the stream must be reset via a call to +gtk_media_stream_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 +gtk_media_stream_play() or gtk_media_stream_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 #GtkMediaFile will unset +errors when a new source is set with ie gtk_media_file_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 +gtk_media_stream_set_loop() for details. + + + %TRUE if the stream should loop + + + + + a #GtkMediaStream + + + + + + Returns whether the audio for the stream is muted. +See gtk_media_stream_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 gtk_media_stream_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 and 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 gtk_media_stream_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 + + + + + + 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 gtk_media_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 + + + + + + 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 +#GdkGLContexts or sync to the #GdkFrameClock. + +Whoever calls this function is responsible for calling +gtk_media_stream_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 gtk_media_stream_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 GtkMediaStream:seeking property will be set. + +When calling gtk_media_stream_seek() during an ongoing seek operation, +the new seek wil 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 gtk_media_stream_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 gtk_media_stream_seek_failed() for the other way of +ending a seek. + + + + + + + a #GtkMediaStream + + + + + + Sets whether the stream should loop, ie 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 + + + + + + Resets a given media stream implementation. gtk_media_stream_prepared() +can now be called again. + +This function will also reset any error state the stream was in. + + + + + + + a #GtkMediaStream + + + + + + Undoes a previous call to gtk_media_stream_realize() and 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. + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 one of 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 + gesture = gtk_gesture_multi_press_new (window); + gtk_gesture_single_set_button (GTK_GESTURE_SINGLE (gesture), + GDK_BUTTON_SECONDARY); + g_signal_connect (gesture, "begin", G_CALLBACK (my_popup_handler), menu); +]| + +## Signal handler which displays a popup menu. + +|[<!-- language="C" --> +static void +my_popup_handler (GtkGesture *gesture, + GdkEventSequence *sequence + gpointer data) +{ + GtkMenu *menu = data; + const GdkEvent *event; + + event = gtk_gesture_get_last_event (gesture, sequence); + gtk_menu_popup_at_pointer (menu, event); +} +]| + +# 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 + + + + + + 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 + + + + + + Places @menu on the given monitor. + + + + + + + a #GtkMenu + + + + the monitor to place the menu on + + + + + + Removes the menu from the screen. + + + + + + + a #GtkMenu + + + + + + 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_surface. @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 #GdkSurface @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 + + + + + + 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 + + + + + + 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 #GdkSurfaceTypeHint to use for the menu's #GdkSurface. + +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 #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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: +|[ +<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 + + + + + + + + + + + + + + + + + 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 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 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. + + + + 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. + + + + + + + + + + + the menu item + + + + + + + + + + + + + + + + + + + + + + + + + + + the menu item + + + + the requisition to use as signal data. + + + + + + + + + + + + + + the menu item. + + + + the allocation to use as signal data. + + + + + + + + + + + + + + a #GtkMenuItem + + + + the text you want to set + + + + + + + + + + The text in the @menu_item label. This is the internal + string used by the label, and must not be modified. + + + + + a #GtkMenuItem + + + + + + + + + + + + + + the menu item + + + + + + + + + + + + + + the menu item + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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. + + + + + + + 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. + + + + + + + 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 + + + + + + A 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: +|[ +<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 + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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. + +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 + + + + + + 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 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 #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 + + + + 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. + + + + + 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 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 #Gdk + + + + + + Sets the transient parent for windows shown by the +#GtkMountOperation. + + + + + + + a #GtkMountOperation + + + + transient parent of the window, or %NULL + + + + + + + + + + + + + + + + + + + + + + + + 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: +|[ +<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 the #GtkNotebookPage for @child. + + + the #GtkNotebookPage for @child + + + + + a #GtkNotebook + + + + a child of @notebook + + + + + + Returns a #GListModel that contains the pages of the notebook, +and can be used to keep an up-to-date view. + + + a #GListModel for the notebook's children + + + + + a #GtkNotebook + + + + + + 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 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 + + + + + + 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, + GdkDrag *drag, + GtkSelectionData *data, + guint time, + gpointer user_data) + { + GtkWidget *notebook; + GtkWidget **child; + + notebook = gtk_drag_get_source_widget (drag); + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the notebook child to which @page belongs. + + + the child to which @page belongs + + + + + a #GtkNotebookPage + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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) + + + + The #GtkOrientable interface is implemented by all 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”. + +#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. + + + + Defines how content overflowing a given area should be handled, such as +with gtk_widget_set_overflow(). This 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. + + + + 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. + +# 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 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:clip-overlay +child property for @widget. + + + 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 + + + + + + Convenience function to set the value of the #GtkOverlay:clip-overlay +child property for @widget. + + + + + + + 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 ::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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + Represents the packing location #GtkBox children + + 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 (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 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 gtk_pad_controller_set_action_entries() or +gtk_pad_controller_set_action(). + +Be aware that pad events will only be delivered to #GtkWindows, 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 + + + + + + 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 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. + +|[<!-- 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 + + + + + + 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. + + + + + + + + + + The "resize-child1" property determines whether the first child expands and +shrinks along with the paned widget. + + + + The "resize-child2" property determines whether the second child expands and +shrinks along with the paned widget. + + + + The "shrink-child1" property determines whether the first child can be made +smaller than its requisition. + + + + The "shrink-child2" property determines whether the second child can be made +smaller than its requisition. + + + + 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 + + + + + + + #GtkPasswordEntry is entry that has been tailored for entering secrets. +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. + +Optionally, it can offer a way to reveal the contents in clear text. + +GtkPasswordEntry provides only minimal API and should be used with the +#GtkEditable API. + + + + + + Creates a #GtkPasswordEntry. + + + a new #GtkPasswordEntry + + + + + Returns whether the entry is showing a clickable icon +to reveal the contents of the entry in clear text. + + + %TRUE if an icon is shown + + + + + a #GtkPasswordEntry + + + + + + Sets whether the entry should have a clickable icon +to show the contents of the entry in clear text. + +Setting this to %FALSE also hides the text again. + + + + + + + a #GtkPasswordEntry + + + + whether to show the peek icon + + + + + + + + + + + + + + + + + + + + + + + + + Flags that influence the behavior of gtk_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 #GtkWidget::can-target + + + + The #GtkPicture widget displays a #GdkPaintable. 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 that, there’s a convenience function +to do this: +|[<!-- language="C" --> + GtkWidget *widget; + 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 +gdk_texture_new_from_file(), then create the #GtkPicture with +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, gtk_picture_new_for_resource() and gtk_picture_set_resource() +should be used. + +# CSS nodes + +GtkPicture has a single CSS node with the name picture. + + + + + 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 be empty. + +If you need to detect failures to load the file, use +gdk_texture_new_for_file() 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 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, or %NULL + + + + + + Creates a new #GtkPicture displaying @pixbuf. + +This is a utility function that calls gtk_picture_new_for_paintable(), +See that function for details. + +The pixbuf must not be modified after passing it to this function. + + + a new #GtkPicture + + + + + a #GdkPixbuf, or %NULL + + + + + + Creates a new #GtkPicture displaying the file @filename. + +This is a utility function that calls 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 or returns %NULL if +the picture cannot be described textually. + + + the alternative textual description + of @self. + + + + + a #GtkPicture + + + + + + Gets the value set via gtk_picture_set_can_shrink(). + + + %TRUE if the picture can be made smaller than its contents + + + + + a #GtkPicture + + + + + + Gets the #GFile currently displayed if @self is displaying a file. +If @self is not displaying a file, for example when gtk_picture_set_paintable() +was used, then %NULL is returned. + + + The #GFile displayed by @self. + + + + + a #GtkPicture + + + + + + Gets the value set via gtk_picture_set_keep_aspect_ratio(). + + + %TRUE if the self tries to keep the contents' aspect ratio + + + + + a #GtkPicture + + + + + + Gets the #GdkPaintable being displayed by the #GtkPicture. + + + the displayed paintable, or %NULL if + the picture is empty + + + + + 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, the @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 +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 +gtk_widget_set_halign() and gtk_widget_set_valign(). + + + + + + + a #GtkPicture + + + + if @self can be made smaller than its contents + + + + + + Makes @self load and display @file. + +See gtk_picture_new_for_file() for details. + + + + + + + a #GtkPicture + + + + a %GFile or %NULL + + + + + + Makes @self load and display the given @filename. + +This is a utility function that calls gtk_picture_set_file(). + + + + + + + a #GtkPicture + + + + the filename to play + + + + + + 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. + + + + + + + a #GtkPicture + + + + whether to keep aspect ratio + + + + + + Makes @self display the given @paintable. If @paintable is %NULL, +nothing will be displayed. + +See gtk_picture_new_for_paintable() for details. + + + + + + + a #GtkPicture + + + + a #GdkPaintable or %NULL + + + + + + See gtk_picture_new_for_pixbuf() for details. + +This is a utility function that calls gtk_picture_set_paintable(), + + + + + + + a #GtkPicture + + + + a #GdkPixbuf or %NULL + + + + + + Makes @self load and display the resource at the given +@resource_path. + +This is a utility function that calls 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 self it contains. + + + + The #GFile that is displayed or %NULL if none. + + + + Whether the GtkPicture will render its contents trying to preserve the aspect +ratio of the contents. + + + + 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. + + + + 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 + +|[<!-- language="plain" --> +popover +├── arrow +╰── contents.background[.menu] + ╰── <child> +]| + +The contents child node always gets the .background style class and it +gets the .menu style class if the popover 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. + +When styling a popover directly, the popover node should usually not have any +background. + +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 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 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 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 + + + + + + Returns the widget @popover is currently attached to + + + a #GtkWidget + + + + + 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 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. + + + + + + + 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, use gtk_popover_menu_add_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. + +To add a named submenu in a ui file, set the #GtkWidget:name property +of the widget that you are adding as a child of the popover menu. + +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 + +|[ +<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> + <property name="name">more</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> + </child> +</object> +]| + +# 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 +popover's contents node. + + + + + Creates a new popover menu. + + + a new #GtkPopoverMenu + + + + + Adds a submenu to the popover menu. + + + + + + + a #GtkPopoverMenu + + + + a widget to add as submenu + + + + the name for the submenu + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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_check_button_set_draw_indicator())) 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_container_add (GTK_CONTAINER (box), radio1); + gtk_container_add (GTK_CONTAINER (box), radio2); + gtk_container_add (GTK_CONTAINER (window), box); + gtk_widget_show (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 the same group as @gruup + + + The new #GtkRadioToolButton + + + + + An existing #GtkRadioToolButton, or %NULL + + + + + + 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 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 + + + + + + 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 #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 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 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 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + #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 + + + + + + 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. + + + + + + + + + + + + Indicated the relief to be drawn around a #GtkButton. + + Draw a normal relief. + + + 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 + + + + + + + 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. +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 #GtkRevealer:reveal-child property is set to %FALSE. + +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 + + + Floop in from the left + + + Floop in from the right + + + Floop in from the bottom + + + Floop in from the top + + + + #GtkRoot is the interface implemented by all widgets that can act as a toplevel +widget to a hierarchy of widgets. 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. + + + + Finds the GtkRoot associated with the surface. + + + the #GtkRoot that is associated with @surface + + + + + a #GdkSurface + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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, + or %NULL if there is none. + + + + + 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 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 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 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-4.0/gtk.css`. + +You should not use priorities higher than this, to +give the user the last word. + + + + + 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][.top][.bottom] +├── trough +│ ├── [fill] +│ ├── [highlight] +│ ╰── slider +╰── 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 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 #GtkScale:draw-value), there is +subnode with name value. This node will get the .top or .bottom style classes +similar to the marks node. + + + + + + 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. + + + + + + + Creates a #GtkScaleButton, with 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() + + + + + + + + + + + + + + + + + + + + + + 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 +╰── box + ╰── range[.fine-tune] + ╰── trough + ╰── slider +]| + +GtkScrollbar has a main CSS node with name scrollbar and a subnode for its +contents. Both the main node and the box subnode get 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. + +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. + + + + + + Returns the scrollbar's adjustment. + + + the scrollbar's adjustment + + + + + a #GtkScrollbar + + + + + + Makes the scrollbar use the given adjustment. + + + + + + + a #GtkScrollbar + + + + the adjustment to set + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GtkScrolledWindow is a container that accepts a single child widget, makes +that child scrollable 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 +#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:hscrolbar-policy and #GtkScrolledWindow: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 #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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 button press events. If they don't, and 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 + + + + horizontal scroll adjustment + + + + + + 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 + + + + vertical scroll adjustment + + + + + + 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. + + + + 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 ::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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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, the search bar must be told +of a widget to capture key events from through +gtk_search_bar_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 gtk_search_bar_connect_entry(). +The following example shows you how to create a more complex search +entry. + +# CSS nodes + +|[<!-- language="plain" --> +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. + +## Creating a search bar + +[A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/master/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 #GtkEditable + + + + + + 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 @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. + + + + + + + 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 + + + + + + Whether the search mode is on and the search bar shown. + +See gtk_search_bar_set_search_mode() for details. + + + + Whether to show the close button in the search bar. + + + + + + + + + + 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_set_key_capture_widget() to let it +capture key input from another widget. + + + + + + Creates a #GtkSearchEntry, with a find icon when the search field is +empty, and a clear icon when it isn't. + + + a new #GtkSearchEntry + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gets the widget that @entry is capturing key events from. + + + The key capture widget. + + + + + a #GtkSearchEntry + + + + + + 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 gtk_search_bar_set_key_capture_widget() instead, which +will reveal the entry in addition to triggering the search entry. + + + + + + + a #GtkSearchEntry + + + + a #GtkWidget + + + + + + + + + + + + + + + + + + + + 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 ::search-started signal gets emitted when the user initiated +a search on the entry. + + + + + + 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 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 a #GdkPixbuf. + + + if the selection data + contained a recognized image type and it could be converted to a + #GdkTexture, a newly allocated texture is returned, otherwise + %NULL. If the result is non-%NULL it must be freed with + g_object_unref(). + + + + + a #GtkSelectionData + + + + + + Gets the contents of the selection data as array of URIs. + + + 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 #GdkTexture. +The surface is converted to the form determined by +@selection_data->target. + + + %TRUE if the selection was successfully set, + otherwise %FALSE. + + + + + a #GtkSelectionData + + + + a #GdkTexture + + + + + + Sets the contents of the selection from a list of URIs. +The string is converted to the form determined by +@selection_data->target. + + + %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 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. + + + + #GtkSelectionModel is an interface that extends the #GListModel interface by adding +support for selections. 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 mode common selection modes such as +#GtkSingleSelection, 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 row indicating if a row is selected +or not. This can be queried via gtk_selection_model_is_selected(). When the selected +state of one or more rows changes, the model will emit the +#GtkSelectionModel::selection-changed signal by calling the +gtk_selection_model_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 #GListModel::items-changed signal are selected +or not is up to the implementation. + +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, #GtkSelectionModels 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. + + + + Checks if the given item is selected. + + + %TRUE if the item is selected + + + + + a #GtkSelectionModel + + + + the position of the item to query + + + + + + This function allows to query the selection status of multiple elements at once. +It is passed a position and returns a range of elements of uniform selection status. + +If @position is greater than the number of items in @model, @n_items is set to 0. +Otherwise the returned range is guaranteed to include the passed-in position, so +@n_items will be >= 1. + +Positions directly adjacent to the returned range may have the same selection +status as the returned range. + +This is an optimization function to make iterating over a model faster when few +items are selected. However, it is valid behavior for implementations to use a +naive implementation that only ever returns a single element. + + + + + + + a #GtkSelectionModel + + + + the position inside the range + + + + returns the position of the first element of the range + + + + returns the size of the range + + + + returns whether items in @range are selected + + + + + + Requests to select all items in the model. + + + + + + + a #GtkSelectionModel + + + + + + Requests to select an item in the model. + + + + + + + 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. + + + + + + + a #GtkSelectionModel + + + + the first item to select + + + + the number of items to select + + + + whether previously selected items should be unselected + + + + + + Requests to unselect all items in the model. + + + + + + + a #GtkSelectionModel + + + + + + Requests to unselect an item in the model. + + + + + + + a #GtkSelectionModel + + + + the position of the item to unselect + + + + + + Requests to unselect a range of items in the model. + + + + + + + a #GtkSelectionModel + + + + the first item to unselect + + + + the number of items to unselect + + + + + + Checks if the given item is selected. + + + %TRUE if the item is selected + + + + + a #GtkSelectionModel + + + + the position of the item to query + + + + + + This function allows to query the selection status of multiple elements at once. +It is passed a position and returns a range of elements of uniform selection status. + +If @position is greater than the number of items in @model, @n_items is set to 0. +Otherwise the returned range is guaranteed to include the passed-in position, so +@n_items will be >= 1. + +Positions directly adjacent to the returned range may have the same selection +status as the returned range. + +This is an optimization function to make iterating over a model faster when few +items are selected. However, it is valid behavior for implementations to use a +naive implementation that only ever returns a single element. + + + + + + + a #GtkSelectionModel + + + + the position inside the range + + + + returns the position of the first element of the range + + + + returns the size of the range + + + + returns whether items in @range are selected + + + + + + Requests to select all items in the model. + + + + + + + a #GtkSelectionModel + + + + + + Requests to select an item in the model. + + + + + + + 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. + + + + + + + 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 a the selection changes to emit the ::selection-changed +signal. + + + + + + + a #GtkSelectionModel + + + + the first changed item + + + + the number of changed items + + + + + + Requests to unselect all items in the model. + + + + + + + a #GtkSelectionModel + + + + + + Requests to unselect an item in the model. + + + + + + + a #GtkSelectionModel + + + + the position of the item to unselect + + + + + + Requests to unselect a range of items in the model. + + + + + + + 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. +All getter functions are mandatory to implement, but the model does +not need to implement any functions to support 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 widgets using the model. + + + + + + + + + %TRUE if the item is selected + + + + + a #GtkSelectionModel + + + + the position of the item to query + + + + + + + + + + + + + + a #GtkSelectionModel + + + + the position of the item to select + + + + whether previously selected items should be unselected + + + + + + + + + + + + + + a #GtkSelectionModel + + + + the position of the item to unselect + + + + + + + + + + + + + + a #GtkSelectionModel + + + + the first item to select + + + + the number of items to select + + + + whether previously selected items should be unselected + + + + + + + + + + + + + + a #GtkSelectionModel + + + + the first item to unselect + + + + the number of items to unselect + + + + + + + + + + + + + + a #GtkSelectionModel + + + + + + + + + + + + + + a #GtkSelectionModel + + + + + + + + + + + + + + a #GtkSelectionModel + + + + the position inside the range + + + + returns the position of the first element of the range + + + + returns the size of the range + + + + returns whether items in @range are selected + + + + + + + + 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-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 +gtk_settings_get_for_display(), 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 display. + + + + Gets the #GtkSettings object for the default display, creating +it if necessary. See 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 + + + + + + + + + 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 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 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. + + + + + + + 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. + + + + + + + + + + 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. + + + + 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. + + + + + + + The time for a button or touch press to be considered a "long press". + + + + 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 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. + + + + + + + + + + + + + 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 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 there 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. + + + 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 #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 +for 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://gitlab.gnome.org/GNOME/gtk/tree/master/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://gitlab.gnome.org/GNOME/gtk/tree/master/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://gitlab.gnome.org/GNOME/gtk/tree/master/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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GtkSingleSelection is an implementation of the #GtkSelectionModel interface +that allows selecting a single element. It is the default selection method +used by list widgets in GTK. + + + + + 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 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 + + + + + + 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 GtkSingleSelection:autoselect will cause the +unselecting to not work, so it practically makes no sense to set +both at the same time the same time.. + + + + + + + a #GtkSingleSelection + + + + %TRUE to allow unselecting + + + + + + 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 GtkSingleSelection: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. + + + + + + + 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 model being managed + + + + Position of the selected item + + + + The selected item + + + + + + + + + + + #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: +|[ +<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 + + + + + + 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 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 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 + + + + #GtkSliceListModel is a list model that takes a list model and presents a slice of +that 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. + + + + Creates a new slice model that presents the slice from @offset to +@offset + @size our of the given @model. + + + A new #GtkSliceListModel + + + + + The model to use + + + + the offset of the slice + + + + maximum size of the slice + + + + + + Creates a new empty #GtkSliceListModel for the given @item_type that +can be set up later. + + + a new empty #GtkSliceListModel + + + + + the type of items + + + + + + Gets the model that is curently 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 #GType for elements of this object + + + + Child model to take slice from + + + + Offset of slice + + + + Maximum size of slice + + + + + + + + + + + GtkSnapshot is an auxiliary object that assists in creating #GskRenderNodes +in the #GtkWidget::snapshot vfunc. 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 the one that gtk_snapshot_append_… +functions operate on. Use the gtk_snapshot_push_… functions and gtk_snapshot_pop() +to change the current node. + +The typical way to obtain a GtkSnapshot object is as an argument to +the #GtkWidget::snapshot vfunc. If you need to create your own GtkSnapshot, +use gtk_snapshot_new(). + + + Creates a new #GtkSnapshot. + + + a newly-allocated #GtkSnapshot + + + + + Appends a stroked border rectangle inside the given @outline. The +4 sides of the border can have different widths and colors. + + + + + + + a #GtkSnapshot + + + + 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. + + + + + + + + Creates a new render node 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 #GdkRGBA to draw + + + + the bounds for the new node + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + a pointer to an array of #GskColorStop 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 + + + + + + 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 + + + + a pointer to an array of #GskColorStop 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. + + + + + + + a #GtkSnapshot + + + + the #GdkTexture to render + + + + the bounds for the new node + + + + + + Returns the node that was constructed by @snapshot +and frees @snapshot. + + + a newly-created #GskRenderNode + + + + + a #GtkSnapshot + + + + + + Returns a paintable for the node that was +constructed by @snapshot and frees @snapshot. + + + a newly-created #GdkPaintable + + + + + a #GtkSnapshot + + + + The size of the resulting paintable + or %NULL to use the bounds of the snapshot + + + + + + Applies a perspective projection transform. + +See 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 2 images with the given blend mode. + +Until the first call to 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 gtk_snapshot_pop(). + +Calling this function requires 2 subsequent calls to gtk_snapshot_pop(). + + + + + + + a #GtkSnapshot + + + + blend mode to use + + + + + + Blurs an image. + +The image is recorded until the next call to gtk_snapshot_pop(). + + + + + + + a #GtkSnapshot + + + + the blur radius to use + + + + + + Clips an image to a rectangle. + +The image is recorded until the next call to gtk_snapshot_pop(). + + + + + + + a #GtkSnapshot + + + + the rectangle to clip to + + + + + + Modifies the colors of an image by applying an affine transformation +in RGB space. + +The image is recorded until the next call to gtk_snapshot_pop(). + + + + + + + a #GtkSnapshot + + + + the color matrix to use + + + + the color offset to use + + + + + + Snapshots a cross-fade operation between two images with the +given @progress. + +Until the first call to gtk_snapshot_pop(), the start image +will be snapshot. After that call, the end image will be recorded +until the second call to gtk_snapshot_pop(). + +Calling this function requires 2 calls to 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 + + + + + + Modifies the opacity of an image. + +The image is recorded until the next call to 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 gtk_snapshot_pop(). + + + + + + + a #GtkSnapshot + + + + the bounds within which to repeat + + + + the bounds of the child + + + + + + Clips an image to a rounded rectangle. + +The image is recorded until the next call to 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 gtk_snapshot_pop(). + + + + + + + a #GtkSnapshot + + + + the first shadow specification + + + + number of shadow specifications + + + + + + 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 #GtkStyleContext to use + + + + 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 #GtkStyleContext to use + + + + 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 #GtkStyleContext to use + + + + 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 #GtkStyleContext to use + + + + 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 +gtk_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. + + + + + + + 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 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 of saved states for @snapshot. When +gtk_snapshot_restore() is called, @snapshot will be restored to +the saved state. Multiple calls to gtk_snapshot_save() and +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 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. 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 gtk_snapshot_unref(). + + + the constructed #GskRenderNode + + + + + 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 gtk_snapshot_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 + + + + + + + + + + #GtkSortListModel is a list model that takes a list model and +sorts its elements according to a compare function. + +#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. + + + + Creates a new sort list model that uses the @sort_func to sort @model. + + + a new #GtkSortListModel + + + + + the model to sort + + + + sort function or %NULL to not sort items + + + + user data passed to @sort_func + + + + destroy notifier for @user_data + + + + + + Creates a new empty sort list model set up to return items of type @item_type. +It is up to the application to set a proper sort function and model to ensure +the item type is matched. + + + a new #GtkSortListModel + + + + + the type of the items that will be returned + + + + + + Gets the model currently sorted or %NULL if none. + + + The model that gets sorted + + + + + a #GtkSortListModel + + + + + + Checks if a sort function is currently set on @self + + + %TRUE if a sort function is set + + + + + a #GtkSortListModel + + + + + + Causes @self to resort all items in the model. + +Calling this function is necessary when data used by the sort +function has changed. + + + + + + + a #GtkSortListModel + + + + + + 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 the function used to sort items. The function will be called for every +item and must return an integer less than, equal to, or greater than zero if +for two items from the model if the first item is considered to be respectively +less than, equal to, or greater than the second. + + + + + + + a #GtkSortListModel + + + + sort function or %NULL to not sort items + + + + user data passed to @sort_func + + + + destroy notifier for @user_data + + + + + + If a sort function is set for this model + + + + The #GType for items of this model + + + + The model being sorted + + + + + + + + + + + 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 +╰── box.horizontal + ├── text + │ ├── undershoot.left + │ ╰── undershoot.right + ├── button.down + ╰── button.up +]| + +|[<!-- language="plain" --> +spinbutton.vertical +╰── box.vertical + ├── button.up + ├── text + │ ├── undershoot.left + │ ╰── undershoot.right + ╰── 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 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. + +## 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); + + // 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 (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. + +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 (GTK_WINDOW_TOPLEVEL); + + // 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 (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_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 + + + + + + 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_spin_button_set_text (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. + +GtkStack maintains a #GtkStackPage object for each added +child, which holds additional per-child properties. You +obtain the #GtkStackPage for a child with gtk_stack_get_page(). + +# GtkStack as GtkBuildable + +To set child-specific properties in a .ui file, create GtkStackPage +objects explictly, and set the child widget as a property on it: +|[ + <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. + + + + + 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 #GtkStackPage object for @child. + + + the #GtkStackPage for @child + + + + + a #GtkStack + + + + a child of @stack + + + + + + Returns a #GListModel that contains the pages of the stack, +and can be used to keep and up-to-date view. The model also +implements #GtkSelectionModel 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. +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. + +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the stack child to which @page belongs. + + + the child to which @page belongs + + + + + a #GtkStackPage + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + 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 + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 display through +gtk_style_context_add_provider_for_display(). 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 +#GdkDisplay 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 display yourself to the created style context through +gtk_style_context_set_path() and possibly gtk_style_context_set_display(). +See the “Foreign drawing“ example in gtk4-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. + +# 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-4.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 @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 gtk_style_context_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 + + + + + + This function recomputes the styles for all widgets under a particular +#GdkDisplay. 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 #GdkDisplay + + + + + + + + + + + + + + + + + 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_display(). + +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_display(). + + + + + + + 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 + + + + + + Retrieves several style property values from @context for a +given state. + +See gtk_style_context_get_property() for details. + +As with g_object_get(), a copy is made of the property contents for +pointer-valued properties, and the caller is responsible for freeing the +memory in the appropriate manner for the type. For example, by calling +g_free() or g_object_unref(). Non-pointer-valued properties, such as +integers, are returned by value and do not need to be freed. + + + + + + + a #GtkStyleContext + + + + Name of the first property + + + + property name /return value pairs, followed by %NULL + + + + + + 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 + + + + return value for the border settings + + + + + + Gets the foreground color for a given state. + +See gtk_style_context_get_property() and +#GTK_STYLE_PROPERTY_COLOR for details. + + + + + + + a #GtkStyleContext + + + + return value for the foreground color + + + + + + Returns the #GdkDisplay to which @context is attached. + + + a #GdkDisplay. + + + + + 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 + + + + 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 + + + + 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 current 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. + +When @value is no longer needed, g_value_unset() must be called +to free any allocated memory. + + + + + + + a #GtkStyleContext + + + + style property name + + + + return location for the style property value + + + + + + Returns the scale used for assets. + + + the scale + + + + + 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 style property values from @context for a given state. + +See gtk_style_context_get_property() for details. + +As with g_object_get(), a copy is made of the property contents for +pointer-valued properties, and the caller is responsible for freeing the +memory in the appropriate manner for the type. For example, by calling +g_free() or g_object_unref(). Non-pointer-valued properties, such as +integers, are returned by value and do not need to be freed. + + + + + + + a #GtkStyleContext + + + + Name of the first property + + + + 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 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 + + + + + + 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 + + + + + + Removes @class_name from @context. + + + + + + + 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 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 + + + + + + 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 +gtk_widget_get_style_context(), you do not need to +call this yourself. + + + + + + + a #GtkStyleContext + + + + a #GdkDisplay + + + + + + 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 + + + + + + Sets the state to be used for style matching. + + + + + + + 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. + + + 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. + + 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 + + + + 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_display(). + + + + + + + + #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 +├── label +├── label +╰── slider +]| + +GtkSwitch has four css nodes, the main node with the name switch and subnodes +for the slider and the on and off labels. Neither of them is using any style classes. + + + + + + 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 @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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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_UNSORTED_SORT_COLUMN_ID can be used to make a +#GtkTreeSortable use no sorting. + +See also gtk_tree_sortable_set_sort_column_id() + + + + + The #GtkText 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_text_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_text_set_invisible_char(). + +If you are looking to add icons or progress display in an entry, look +at #GtkEntry. There other alternatives for more specialized use cases, +such as #GtkSearchEntry. + +If you need multi-line editable text, look at #GtkTextView. + +# CSS nodes + +|[<!-- language="plain" --> +text[.read-only] +├── placeholder +├── undershoot.left +├── undershoot.right +├── [selection] +├── [block-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 below text 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 self. + + + a new #GtkText. + + + + + Creates a new self with the specified text buffer. + + + a new #GtkText + + + + + The buffer to use for the new #GtkText. + + + + + + Retrieves the value set by gtk_text_set_activates_default(). + + + %TRUE if the self will activate the default widget + + + + + a #GtkText + + + + + + Gets the attribute list that was set on the self using +gtk_text_set_attributes(), if any. + + + the attribute list, or %NULL + if none was set. + + + + + a #GtkText + + + + + + Get the #GtkEntryBuffer object which holds the text for +this self. + + + A #GtkEntryBuffer object. + + + + + a #GtkText + + + + + + Gets the value of the #GtkText:input-hints property. + + + + + + + a #GtkText + + + + + + Gets the value of the #GtkText:input-purpose property. + + + + + + + a #GtkText + + + + + + Retrieves the character displayed in place of the real characters +for entries with visibility set to false. +See gtk_text_set_invisible_char(). + + + the current invisible char, or 0, if the self does not + show invisible text at all. + + + + + a #GtkText + + + + + + Retrieves the maximum allowed length of the text in +@self. See gtk_text_set_max_length(). + +This is equivalent to getting @self's #GtkEntryBuffer and +calling gtk_entry_buffer_get_max_length() on it. + + + the maximum allowed number of characters + in #GtkText, or 0 if there is no maximum. + + + + + a #GtkText + + + + + + Gets the value set by gtk_text_set_overwrite_mode(). + + + whether the text is overwritten when typing. + + + + + a #GtkText + + + + + + Retrieves the text that will be displayed when @self 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 #GtkText + + + + + + Gets the tabstops that were set on the self using gtk_text_set_tabs(), if +any. + + + the tabstops, or %NULL if none was set. + + + + + a #GtkText + + + + + + Retrieves the current length of the text in +@self. + +This is equivalent to getting @self's #GtkEntryBuffer and +calling gtk_entry_buffer_get_length() on it. + + + the current number of characters + in #GtkText, or 0 if there are none. + + + + + a #GtkText + + + + + + Retrieves whether the text in @self is visible. +See gtk_text_set_visibility(). + + + %TRUE if the text is currently visible + + + + + a #GtkText + + + + + + Causes @self to have keyboard focus. + +It behaves like gtk_widget_grab_focus(), +except that it doesn't select the contents of the 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. + + + + + + + a #GtkText + + + + + + If @activates is %TRUE, pressing Enter in the @self will activate the default +widget for the window containing the self. This usually means that +the dialog box containing the self will be closed, since the default +widget is usually one of the dialog buttons. + + + + + + + a #GtkText + + + + %TRUE to activate window’s default widget on Enter keypress + + + + + + Sets a #PangoAttrList; the attributes in the list are applied to the +self text. + + + + + + + a #GtkText + + + + a #PangoAttrList + + + + + + Set the #GtkEntryBuffer object which holds the text for +this widget. + + + + + + + a #GtkText + + + + a #GtkEntryBuffer + + + + + + Sets the #GtkText:input-hints property, which +allows input methods to fine-tune their behaviour. + + + + + + + a #GtkText + + + + the hints + + + + + + Sets the #GtkText:input-purpose property which +can be used by on-screen keyboards and other input +methods to adjust their behaviour. + + + + + + + a #GtkText + + + + the purpose + + + + + + Sets the character to use in place of the actual text when +gtk_text_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 #GtkText + + + + 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 @self's #GtkEntryBuffer and +calling gtk_entry_buffer_set_max_length() on it. +]| + + + + + + + a #GtkText + + + + the maximum length of the self, 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 in the #GtkText. + + + + + + + a #GtkText + + + + new value + + + + + + Sets text to be displayed in @self when it is empty. + +This can be used to give a visual hint of the expected +contents of the self. + + + + + + + a #GtkText + + + + a string to be displayed when @self is empty and unfocused, or %NULL + + + + + + Sets a #PangoTabArray; the tabstops in the array are applied to the self +text. + + + + + + + a #GtkText + + + + a #PangoTabArray + + + + + + Sets whether the contents of the self 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 self 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 +gtk_text_set_invisible_char(). + +Note that you probably want to set #GtkText:input-purpose +to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to +inform input methods about the purpose of this self, +in addition to setting visibility to %FALSE. + + + + + + + a #GtkText + + + + %TRUE if the contents of the self are displayed + as plaintext + + + + + + Unsets the invisible char previously set with +gtk_text_set_invisible_char(). So that the +default invisible char is used again. + + + + + + + a #GtkText + + + + + + + + + A list of Pango attributes to apply to the text of the self. + +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. + + + + + + + + + + Which IM (input method) module should be used for this self. +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 #GtkText: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 +#GtkText:visibility. + + + + + + + Whether the invisible char has been set for the #GtkText. + + + + + + + If text is overwritten when typing in the #GtkText. + + + + The text that will be displayed in the #GtkText when it is empty +and unfocused. + + + + If :populate-all is %TRUE, the #GtkText::populate-popup +signal is also emitted for touch popups. + + + + + + + + + + + + + When %TRUE, pasted multi-line text is truncated to the first line. + + + + + + + + + + The ::activate signal is emitted when the user hits +the Enter key. + +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 ::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 @self. + +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 @self, 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 self. + +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 #GtkText: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 self. + +The default bindings for this signal is Insert. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + You may wish to begin by reading the +[text widget conceptual overview][TextWidget] +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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 texture, 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 texture + + + + a #GdkTexture + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #GdkClipboard returned by gdk_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 + + + + + + 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 #GdkClipboard 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 #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 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 + + + + + + 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 + + + + + + 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. + +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. + +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 + + + + + + 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 + + + + + + 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 texture 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 + + + + + + Copies text, tags, and texture 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 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 texture, 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 texture + + + + a #GdkTexture + + + + + + 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 #GdkClipboard 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 + + + + + + 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 #GdkClipboard added with +gtk_text_buffer_add_selection_clipboard(). + + + + + + + a #GtkTextBuffer + + + + a #GdkClipboard 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 + + + + + + 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 + + + + + + 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-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 ::insert-texture signal is emitted to insert a #GdkTexture +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 @texture. + +See also: gtk_text_buffer_insert_texture(). + + + + + + position to insert @texture in @textbuffer + + + + the #GdkTexture to be inserted + + + + + + 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 #GdkClipboard 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkTextBuffer + + + + location to insert the texture + + + + a #GdkTexture + + + + + + + + + + + + + + a #GtkTextBuffer + + + + location to insert the anchor + + + + a #GtkTextChildAnchor + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkTextBuffer + + + + a #GtkTextTag + + + + one bound of range to be tagged + + + + other bound of range to be tagged + + + + + + + + + + + + + + a #GtkTextBuffer + + + + a #GtkTextTag + + + + one bound of range to be untagged + + + + other bound of range to be untagged + + + + + + + + + + + + + + a #GtkTextBuffer + + + + + + + + + + + + + + a #GtkTextBuffer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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] +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 + + + + + + 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 + + + + + + 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 + + + + + + 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 texture 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 + + + + + + If the element at @iter is a texture, the texture is returned +(with no new reference count added). Otherwise, %NULL is returned. + + + the texture at @iter + + + + + an iterator + + + + + + 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] +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 + + + + + + + + + + + + + + + + + + + + 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 textures or child widgets. + + Search only visible data. A search match may +have invisible text interspersed. + + + Search only text. A match may have textures 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] +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 “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. Configure the tag using object arguments, +i.e. using g_object_set(). + + + a new #GtkTextTag + + + + + tag name, or %NULL + + + + + + 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. + + + + + + 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 #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 #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 #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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + You may wish to begin by reading the +[text widget conceptual overview][TextWidget] +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: +|[ +<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] +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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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_surface_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 + + + + + + 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 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_surface_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_surface_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 + + + + + + Fills @visible_rect with the currently-visible +region of the buffer, in buffer coordinates. Convert to window coordinates +with gtk_text_view_buffer_to_surface_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 +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 +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 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,” it doesn’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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + Private value, used internally + + + 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 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 #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); + + 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); + 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 (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. + + + + + + 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. + + + + + + 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 + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 and #GtkToolButton:label. +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. + +The icon of a #GtkToolButton is determined by the +#GtkToolButton:icon-widget property. If +#GtkToolButton:icon-widget is non-%NULL, then +that widget is used as the icon. Otherwise it does not have an 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 + + + + + + + + + + + + + + + + + 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. 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 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 or +#GtkToolButton:icon-widget properties. + + + + + + + a #GtkToolButton + + + + the name of the themed icon + + + + + + Sets @icon as the widget used as icon on @button. + + + + + + + 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, @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, @button does not have a label. + + + + + + + a #GtkToolButton + + + + the widget used as label, 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 or #GtkToolButton:icon-widget + + + + + + + + + + + + + + + + + + + + + + This signal is emitted when the tool button is clicked with the mouse +or activated with the keyboard. + + + + + + + + + The parent class. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #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 + + + + + + + + + + + + + + + + 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 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 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 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 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() +to find out what the toolbar should look like and change +themselves accordingly. + + + + + + + + + The parent class. + + + + + + + + + + + + + + + + + + + + + + + + a #GtkToolItem + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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 + + + + + + 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 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 + + + + + + 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. + + + + + + + + + the current orientation of @shell + + + + + a #GtkToolShell + + + + + + + + + + the current style of @shell + + + + + a #GtkToolShell + + + + + + + + + + + + + + a #GtkToolShell + + + + + + + + + + the current text orientation of @shell + + + + + a #GtkToolShell + + + + + + + + + + the current text alignment of @shell + + + + + a #GtkToolShell + + + + + + + + + + the current ellipsize mode of @shell + + + + + a #GtkToolShell + + + + + + + + + + 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 GtkToolItem 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 + + + + + + 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 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 + + + + + + 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 a toolbar style set with gtk_toolbar_set_style(), so that +user preferences will be used to determine the toolbar style. + + + + + + + a #GtkToolbar + + + + + + + + + + + + + + + + + + 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 keyboard, @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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + 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, 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 + + + + + + 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 + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + whether a new row was created before position @dest + + + + + a #GtkTreeDragDest + + + + row to drop in front of + + + + data to drop + + + + + + + + + + %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 + + + + + + + + + + + + + + + %TRUE if the row can be dragged + + + + + a #GtkTreeDragSource + + + + row on which user is initiating a drag + + + + + + + + + + %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 + + + + + + + + + + %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() + + + + + + #GtkTreeListModel is a #GListModel implementation that can expand rows +by creating new child list models on demand. + + + + Creates a new empty #GtkTreeListModel displaying @root with all rows collapsed. + + + a newly created #GtkTreeListModel. + + + + + %TRUE to pass through items from the models + + + + The #GListModel to use as root + + + + %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 gtk_tree_list_model_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 gtk_tree_list_model_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 + + + + + + If this function returns %FALSE, the #GListModel functions for @self +return custom #GtkTreeListRow objects. You need to call +gtk_tree_list_row_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 gtk_tree_list_model_get_row() +to get the custom #GtkTreeListRows. + + + %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 gtk_tree_list_model_get_child_row(). + + + The row item + + + + + a #GtkTreeListModel + + + + the position of the row to fetch + + + + + + 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 gtk_tree_list_model_set_expanded(). + + + + + + + a #GtkTreeListModel + + + + %TRUE to make the model autoexpand its rows + + + + + + If all rows should be expanded by default + + + + The root model displayed + + + + If %FALSE, the #GListModel functions for this object return custom +#GtkTreeListRow 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 leave 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 + + + + + + + + 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 #GtkTreeListModelCreateModelFunc +and contains the original items, no matter what value +#GtkTreeListModel: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 destroyed. + + + 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 value returned by this function never changes until the +row is destroyed. + + + The item of this row + or %NULL when the row was destroyed + + + + + 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 destroyed. + + + 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 +gtk_tree_list_row_get_expanded() + +If a row is expandable never changes until the row is destroyed. + + + %TRUE if the row is expandable + + + + + a #GtkTreeListRow + + + + + + Expands or collapses a row. + +If a row is expanded, the model of calling the +#GtkTreeListModelCreateModelFunc 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 + + + + + + + + + + + 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 + + + + + + Creates a new #GtkTreeModel, with @child_model as the child model. + + + A new #GtkTreeModel. + + + + + A #GtkTreeModel + + + + + + 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() + + + + + + + + + + + + + + + + + + a #GtkTreeModel + + + + a #GtkTreePath-struct pointing to the changed row + + + + a valid #GtkTreeIter-struct pointing to the changed row + + + + + + + + + + + + + + a #GtkTreeModel + + + + a #GtkTreePath-struct pointing to the inserted row + + + + a valid #GtkTreeIter-struct pointing to the inserted row + + + + + + + + + + + + + + a #GtkTreeModel + + + + a #GtkTreePath-struct pointing to the changed row + + + + a valid #GtkTreeIter-struct pointing to the changed row + + + + + + + + + + + + + + a #GtkTreeModel + + + + a #GtkTreePath-struct pointing to the previous location of + the deleted row + + + + + + + + + + + + + + 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` + + + + + + + + + + the flags supported by this interface + + + + + a #GtkTreeModel + + + + + + + + + + the number of columns + + + + + a #GtkTreeModel + + + + + + + + + + the type of the column + + + + + a #GtkTreeModel + + + + the column index + + + + + + + + + + %TRUE, if @iter was set + + + + + a #GtkTreeModel + + + + the uninitialized #GtkTreeIter-struct + + + + the #GtkTreePath-struct + + + + + + + + + + a newly-created #GtkTreePath-struct + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + + + + + + + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + the column to lookup the value at + + + + an empty #GValue to set + + + + + + + + + + %TRUE if @iter has been changed to the next node + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + + + + + + + %TRUE if @iter has been changed to the previous node + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + + + + + + + %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 + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct to test for children + + + + + + + + + + the number of children of @iter + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct, or %NULL + + + + + + + + + + %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 + + + + + + + + + + %TRUE, if @iter is set to the parent of @child + + + + + a #GtkTreeModel + + + + the new #GtkTreeIter-struct to set to the parent + + + + the #GtkTreeIter-struct + + + + + + + + + + + + + + a #GtkTreeModel + + + + the #GtkTreeIter-struct + + + + + + + + + + + + + + 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); +} +]| + + + + + + 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). + + + + + + + + + + + + + + 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. @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. + + + TRUE, if there is a selected node. + + + + + A #GtkTreeSelection. + + + + A pointer to set to the #GtkTreeModel, or NULL. + + + + The #GtkTreeIter, or NULL. + + + + + + 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); +]| + + + A #GList containing a #GtkTreePath for each selected row. + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + + + + + + A #GtkTreeSortable + + + + + + + + + + %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 + + + + + + + + + + + + + + A #GtkTreeSortable + + + + the sort column id to set + + + + The sort order of the column + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + 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: +|[ +<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_TEXTURE);` will create a new #GtkTreeStore with three columns, of type +#gint, #gchararray, and #GdkTexture 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] +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: +|[ +<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 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. + + + + + + + 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 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. + + + + + + + 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. + + + + + + + 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 + + + + + + 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 + + + + + + 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. +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(). + + + %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 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 + + + + + + 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. 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. + + + %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. + + + + + + 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. + + + + + + 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 @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 + + + + + + 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. + + + + + + + + + + + + + + + + %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] +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] +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() + + + + + + + + + + + + + + + + + + + + + + + See also gtk_print_settings_set_paper_width(). + + No units. + + + Dimensions in points. + + + Dimensions in inches. + + + Dimensions in millimeters + + + + GtkVideo is a widget to show a #GtkMediaStream. + +It is commonly combined with #GtkMediaControls to give the +user a way to control the playback. + + + + + 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 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 gtk_video_new_for_file(), + + + a new #GtkVideo + + + + + resource path to play back + + + + + + Returns %TRUE if videos have been set to loop via gtk_video_set_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 %TRUE if videos have been set to loop via gtk_video_set_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 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 #GtkImage for display. + +If you want to display a file, consider using 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 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. + + + + If new media files should be set to loop. + + + + The media-stream played + + + + + + + + + + + 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 shadow type of the #GtkViewport. See +gtk_viewport_set_shadow_type(). + + + the shadow type + + + + + a #GtkViewport + + + + + + Sets the shadow type of the viewport. + + + + + + + a #GtkViewport. + + + + the new shadow type. + + + + + + + + + + + + + + + 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 two virtual methods: + +- #GtkWidgetClass.get_request_mode() +- #GtkWidgetClass.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 #GtkWidgetClass.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 #GtkWidgetClass.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 #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_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 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 +(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 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 #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. + +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.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: + +|[<!-- language="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 gtk_widget_measure() +inside your own #GtkWidgetClass.size-allocate() implementation. +These return a request adjusted by #GtkSizeGroup, 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 gtk_widget_measure(). +Otherwise, you would not properly consider widget margins, +#GtkSizeGroup, 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 of %GTK_ALIGN_BASELINE, 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 #GtkWidgetClass.measure() +virtual function. It allows you to report a both a minimum and natural + +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. + +# 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: +|[ +<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: +|[ +<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> +]| + +If the parent widget uses a #GtkLayoutManager, #GtkWidget supports a +custom <layout> element, used to define layout properties: + +|[ +<object class="MyGrid" id="grid1"> + <child> + <object class="GtkLabel" id="label1"> + <property name="label">Description</property> + <layout> + <property name="left-attach">0</property> + <property name="top-attach">0</property> + <property name="row-span">1</property> + <property name="col-span">1</property> + </layout> + </object> + </child> + <child> + <object class="GtkEntry" id="description_entry"> + <layout> + <property name="left-attach">1</property> + <property name="top-attach">0</property> + <property name="row-span">1</property> + <property name="col-span">1</property> + </layout> + </object> + </child> +</object> +]| + +Finally, GtkWidget allows style information such as style classes to +be associated with widgets, using the custom <style> element: +|[ +<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: +|[ +<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. + + + + + 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. + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + Tests if the point at (@x, @y) is contained in @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 (@x, @y). + + + + + the widget to query + + + + X coordinate to test, relative to @widget's origin + + + + Y coordinate to test, relative to @widget's origin + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + 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 + + + + + + Causes @widget (or one of its descendents) to have the keyboard focus +for the #GtkWindow it's inside. + +@widget must be focusable, or have a ::grab_focus implementation that +transfers the focus to a descendant of @widget that is focusable. + + + + + + + a #GtkWidget + + + + + + + + + + + + + + + + + + + + Reverses the effects of gtk_widget_show(), causing the widget to be +hidden (invisible to the user). + + + + + + + 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 + + + + + + This function is only for use in widget implementations. Causes +a widget to be mapped if it isn’t already. + + + + + + + a #GtkWidget + + + + + + 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][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, or %NULL + + + + location to store the natural size, or %NULL + + + + location to store the baseline + position for the minimum size, or %NULL + + + + location to store the baseline + position for the natural size, or %NULL + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates the GDK (windowing system) resources associated with a +widget. For example, @widget->surface 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::realize. + + + + + + + a #GtkWidget + + + + + + + + + + + + + + + + + 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 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 useful in widget implementations. +Causes a widget to be unrealized (frees all GDK resources +associated with the widget, such as @widget->surface). + + + + + + + a #GtkWidget + + + + + + + + + + + + + + + + + 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 + + + + + + Looks up the action in the action groups associated +with @widget and its ancestors, and activates it. + +The action name is expected to be prefixed with the +prefix that was used when adding the action group +with gtk_widget_insert_action_group(). + +The @parameter must match the actions expected parameter +type, as returned by g_action_get_parameter_type(). + + + + + + + a #GtkWidget + + + + a prefixed action name + + + + parameters that required by the action + + + + + + Activate the default.activate action from @widget. + + + + + + + a #GtkWidget + + + + + + 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 @controller to @widget so that it will receive events. You will +usually want to call this function right after creating any kind of +#GtkEventController. + + + + + + + a #GtkWidget + + + + a #GtkEventController that hasn't been + added to a widget yet + + + + + + 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() 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 the id returned from this function 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. + + + + + + This function is only used by #GtkWidget subclasses, to assign a size, +position and (optionally) baseline to their child widgets. + +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. + +For a version that does not take a transform, see gtk_widget_size_allocate() + + + + + + + A #GtkWidget + + + + New width of @widget + + + + New height of @widget + + + + New baseline of @widget, or -1 + + + + Transformation to be applied to @widget + + + + + + 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. + +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 + + + + + + Computes the bounds for @widget in the coordinate space of @target. +FIXME: Explain what "bounds" are. + +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 #GtkWidget to query + + + + the #GtkWidget + + + + the rectangle taking the bounds + + + + + + 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 + + + + + + Translates the given @point in @widget's coordinates to coordinates +relative to @target’s coodinate system. In order to perform this +operation, both widgets must share a common ancestor. + + + %TRUE if the point could be determined, %FALSE on failure. + In this case, 0 is stored in @out_point. + + + + + the #GtkWidget to query + + + + the #GtkWidget 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. + + + %TRUE if the transform could be computed, %FALSE otherwise. + 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. + + + + + a #GtkWidget + + + + the target widget that the matrix will transform to + + + + location to + store the final transformation + + + + + + Tests if the point at (@x, @y) is contained in @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 (@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 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::display-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 + + + + + + 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 context for this drag + + + + + the source widget + + + + the device that starts the drag or %NULL to use the default pointer + + + + The targets (data formats) in which the source can provide the data + + + + A bitmask of the allowed drag actions for this drag + + + + The initial x coordinate to start dragging from, in the coordinate space of @widget. + + + + The initial y coordinate to start dragging from, in the coordinate space of @widget. + + + + + + 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 @drop and the +@dest_target_list, returning the first matching target, otherwise +returning %NULL. @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 %NULL + + + + + drag destination widget + + + + #GdkDrop + + + + 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 #GdkContentFormats, 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 gdk_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, + GdkDrag *drag, + gint x, + gint y, + guint time) +{ + GdkModifierType mask; + + gdk_surface_get_pointer (gtk_widget_get_surface (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 + + + + 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(). + + + + a bitmask of possible actions for a drop onto this @widget. + + + + + + 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 #GdkDrop + + + + the target (form of the data) to retrieve + + + + + + 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_content_formats_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_content_formats_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 #GdkContentFormats, 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 targets that the drag will support, + may be %NULL + + + + 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 source +to @paintable. + + + + + + + a #GtkWidget + + + + A #GdkPaintable + + + + + + 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 + + + + + + Notifies the user about an input-related error on this widget. +If the #GtkSettings:gtk-error-bell setting is %TRUE, it calls +gdk_surface_beep(), otherwise it does nothing. + +Note that the effect of 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 #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. + + + return from the event signal emission (%TRUE if + the event was handled) + + + + + a #GtkWidget + + + + a #GdkEvent + + + + + + 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::snapshot 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. + + + the height of the @widget + + + + + the widget to query + + + + + + Returns the width that has currently been allocated to @widget. + + + 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. + + + + + + + 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 @widget can own the input focus. See +gtk_widget_set_can_focus(). + + + %TRUE if @widget can own the input focus, %FALSE otherwise + + + + + a #GtkWidget + + + + + + Queries whether @widget can be the target of pointer events. + + + %TRUE if @widget can receive pointer events + + + + + a #GtkWidget + + + + + + 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 + + + + + + This is a utility function to get the clipboard object for the +#GdkDisplay that @widget is using. + +Note that this function always works, even when @widget is not +realized yet. + + + the appropriate clipboard object. + + + + + a #GtkWidget + + + + + + Queries the cursor set via gtk_widget_set_cursor(). See that function for +details. + + + the cursor currently in use or %NULL + to use the default. + + + + + a #GtkWidget + + + + + + 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 + + + + + + + + The widget's first child + + + + + a #GtkWidget + + + + + + Returns the current focus child of @widget. + + + The current focus child of @widget, + or %NULL in case the focus child is unset. + + + + + 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 #GdkDisplay 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 + + + + + + Determines whether @widget has a #GdkSurface of its own. See +gtk_widget_set_has_surface(). + + + %TRUE if @widget has a surface, %FALSE otherwise + + + + + 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 + + + + + + Returns the content height of the widget, as passed to its size-allocate implementation. +This is the size you should be using in GtkWidgetClass.snapshot(). For pointer +events, see gtk_widget_contains(). + + + The height of @widget + + + + + 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 + + + + + + + + The widget's last child + + + + + a #GtkWidget + + + + + + Retrieves the layout manager set using gtk_widget_set_layout_manager(). + + + a #GtkLayoutManager + + + + + a #GtkWidget + + + + + + 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-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 + + + + + + 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 + + + + + + + + The widget's next sibling + + + + + a #GtkWidget + + + + + + Fetches the requested opacity for this widget. +See gtk_widget_set_opacity(). + + + the requested opacity for this widget. + + + + + a #GtkWidget + + + + + + Returns the value set via gtk_widget_set_overflow(). + + + The widget's overflow. + + + + + 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::display-changed signal on the widget. + + + the #PangoContext for the widget. + + + + + a #GtkWidget + + + + + + Returns the parent widget of @widget. + + + the parent widget of @widget, or %NULL + + + + + 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 + + + + + + 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_measure() 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 + + + + + + + + The widget's previous sibling + + + + + a #GtkWidget + + + + + + This is a utility function to get the primary clipboard object +for the #GdkDisplay that @widget is using. + +Note that this function always works, even when @widget is not +realized yet. + + + the appropriate clipboard object. + + + + + a #GtkWidget + + + + + + 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 + + + + + + Returns the #GtkRoot widget of @widget or %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, or %NULL + + + + + 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_surface_get_scale_factor(). + + + the scale factor for @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 #GdkDisplay. + + + 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_measure() instead of +this function. + + + + + + + a #GtkWidget + + + + return location for width, or %NULL + + + + return location for height, or %NULL + + + + + + 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 + + + + + + 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 + + + + + + Returns the widget’s surface if it is realized, %NULL otherwise + + + @widget’s surface. + + + + + 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. + +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. + + + 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 + + + + + + Returns the content width of the widget, as passed to its size-allocate implementation. +This is the size you should be using in GtkWidgetClass.snapshot(). For pointer +events, see gtk_widget_contains(). + + + The width of @widget + + + + + 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 (or one of its descendents) to have the keyboard focus +for the #GtkWindow it's inside. + +@widget must be focusable, or have a ::grab_focus implementation that +transfers the focus to a descendant of @widget that is focusable. + + + + + + + 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. + + + %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 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 + + + + + + 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 surface. This allows for +windows which react to mouse click in a nonrectangular region, see +gdk_surface_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 + + + + + + Inserts @widget into the child widget list of @parent. +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. + + + + + + + a #GtkWidget + + + + the parent #GtkWidget to insert @widget into + + + + the new previous sibling of @widget or %NULL + + + + + + Inserts @widget into the child widget list of @parent. +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. + + + + + + + a #GtkWidget + + + + the parent #GtkWidget to insert @widget into + + + + the new next sibling of @widget or %NULL + + + + + + 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 + + + + + + Determines whether @widget can be drawn to. A widget can be drawn +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 #GtkWindows are toplevel widgets. +Toplevel widgets have no parent widget and implement +the #GtkRoot interface. + + + %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 + + + + + + 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][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, or %NULL + + + + location to store the natural size, or %NULL + + + + location to store the baseline + position for the minimum size, or %NULL + + + + location to store the baseline + position for the natural size, or %NULL + + + + + + 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 + + + + + + Returns a #GListModel to track the children of @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 #GListModel tracking @widget's children + + + + + a #GtkWidget + + + + + + Returns a #GListModel to track the #GtkEventControllers of @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 #GListModel tracking @widget's controllers + + + + + a #GtkWidget + + + + + + Finds the descendant of @widget (including @widget itself) closest +to the screen at the point (@x, @y). The point 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 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 hilighting and delivering events. + + + The widget descendant at the given + coordinate or %NULL if none. + + + + + 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 + + + + + + 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 + + + + + + Schedules this widget to be redrawn in paint phase of the +current or the next frame. This means @widget's GtkWidgetClass.snapshot() +implementation will be called. + + + + + + + a #GtkWidget + + + + + + 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->surface 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::realize. + + + + + + + a #GtkWidget + + + + + + Registers a #GdkSurface with the widget and sets it up so that +the widget receives events for it. Call gtk_widget_unregister_surface() +when destroying the surface. + +Before 3.8 you needed to call gdk_surface_set_user_data() directly to set +this up. This is now deprecated and you should use gtk_widget_register_surface() +instead. Old code will keep working as is, although some new features like +transparency might not work perfectly. + + + + + + + a #GtkWidget + + + + a #GdkSurface + + + + + + 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 @controller from @widget, so that it doesn't process +events anymore. It 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 #GtkWidget + + + + a #GtkEventController + + + + + + 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() + + + + + + 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 + + + + + + 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. + +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. + + + + + + Specifies whether @widget can own the input focus. + +Note that having @can_focus be %TRUE is only one of the +necessary conditions for being focusable. A widget must +also be sensitive and not have a ancestor that is marked +as not child-focusable in order to receive 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 can be the target of pointer events. + + + + + + + a #GtkWidget + + + + whether this widget should be able to receive pointer events + + + + + + 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 cursor to be shown when pointer devices point towards @widget. + +If the @cursor is NULL, @widget will use the cursor inherited from the +parent widget. + + + + + + + a #GtkWidget + + + + the new cursor or %NULL to use the default + cursor + + + + + + Sets a named cursor to be shown when pointer devices point towards @widget. + +This is a utility function that creates a cursor via +gdk_cursor_new_from_name() and then sets it on @widget with +gtk_widget_set_cursor(). See those 2 functions for details. + +On top of that, this function allows @name to be %NULL, which will +do the same as calling gtk_widget_set_cursor() with a %NULL cursor. + + + + + + + a #GtkWidget + + + + The name of the cursor or %NULL to use the default + cursor + + + + + + 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 + + + + + + Set @child as the current focus child of @widget. The previous +focus child will be unset. + +This function is only suitable for widget implementations. +If you want a certain widget to get the input focus, call +gtk_widget_grab_focus() on it. + + + + + + + a #GtkWidget + + + + a direct child widget of @widget or %NULL + to unset the focus child of @widget + + + + + + 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 #GdkDisplay 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 + + + + + + Specifies whether @widget has a #GdkSurface of its own. Note that +all realized widgets have a non-%NULL “window” pointer +(gtk_widget_get_surface() never returns a %NULL surface when a widget +is realized), but for many of them it’s actually the #GdkSurface 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_surface = %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 surface. + + + + + + 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. + + + + + + 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 + + + + + + Sets the layout manager delegate instance that provides an implementation +for measuring and allocating the children of @widget. + + + + + + + a #GtkWidget + + + + a #GtkLayoutManager + + + + + + 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 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 + + + + + + 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 displays with a compositing manager +running. See gdk_display_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. + + + + + + + a #GtkWidget + + + + desired opacity, between 0 and 1 + + + + + + Sets how @widget treats content that is drawn outside the widget's content area. +See the definition of #GtkOverflow for details. + +This setting is provided for widget implementations and should not be used by +application code. + +The default value is %GTK_OVERFLOW_VISIBLE. + + + + + + + a #GtkWidget + + + + desired overflow + + + + + + This function is useful only when implementing subclasses of +#GtkWidget. +Sets @parent as the parent widget of @widget, and takes care of +some details such as updating the state and style of the child +to reflect its new location and resizing the parent. The opposite +function is gtk_widget_unparent(). + + + + + + + a #GtkWidget + + + + parent widget + + + + + + 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. + + + + + + + a #GtkWidget + + + + whether or not @widget can be a default widget. + + + + + + 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. 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 + + + + + + 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 #GdkSurfaces are created in #GtkWidget::realize, +gdk_surface_set_support_multidevice() will have to be called manually on them. + + + + + + + a #GtkWidget + + + + %TRUE to support input from multiple devices. + + + + + + Sets a widget’s surface. This function should only be used in a +widget’s #GtkWidget::realize implementation. The %surface passed is +usually either new surface created with gdk_surface_new(), or the +surface of its parent widget as returned by +gtk_widget_get_parent_surface(). + +Widgets must indicate whether they will create their own #GdkSurface +by calling gtk_widget_set_has_surface(). This is usually done in the +widget’s init() function. + +Note that this function does not add any reference to @surface. + + + + + + + a #GtkWidget + + + + a #GdkSurface + + + + + + 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 + + + + + + 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 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 + + + + + + This is a simple form of gtk_widget_allocate() that takes the new position +of @widget as part of @allocation. + + + + + + + a #GtkWidget + + + + position and size to be allocated to @widget + + + + The baseline of the child, or -1 + + + + + + When a widget receives a call to the snapshot function, it must send +synthetic #GtkWidget::snapshot calls to all children. This function +provides a convenient way of doing this. A widget, when it receives +a call to its #GtkWidget::snapshot function, calls +gtk_widget_snapshot_child() once for each child, passing in +the @snapshot the widget received. + +gtk_widget_snapshot_child() takes care of translating the origin of +@snapshot, and deciding whether the child needs to be snapshot. + + + + + + + a #GtkWidget + + + + a child of @widget + + + + #GtkSnapshot as passed to the widget. In particular, no + calls to gtk_snapshot_translate() or other transform calls should + have been made. + + + + + + Translate 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 toplevel. + + + %FALSE if @src_widget and @dest_widget have no common + ancestor. In this case, 0 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 parent widgets to dissociate @widget +from the parent. + + + + + + + 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->surface). + + + + + + + a #GtkWidget + + + + + + Unregisters a #GdkSurface from the widget that was previously set up with +gtk_widget_register_surface(). You need to call this when the surface is +no longer used by the widget, such as when you destroy it. + + + + + + + a #GtkWidget + + + + a #GdkSurface + + + + + + 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 + + + + + + + + + + + + The name of this widget in the CSS tree. + + + + The cursor used by @widget. See gtk_widget_set_cursor() for details. + + + + 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. + + + + + + + Whether to expand horizontally. See gtk_widget_set_hexpand(). + + + + Whether to use the #GtkWidget:hexpand property. See gtk_widget_get_hexpand_set(). + + + + + + + The #GtkLayoutManager instance to use to compute the preferred size +of the widget, and allocate its children. + + + + 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 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 + + + + How content outside the widget's content area is treated. + + + + + + + + + + The #GtkRoot widget of the widget tree containing this widget or %NULL if +the widget is not contained in a root widget. + + + + The scale factor of the widget. See gtk_widget_get_scale_factor() for +more details about widget scaling. + + + + + + + The widget's surface if it is realized, %NULL otherwise. + + + + 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 ::accel-closures-changed signal gets emitted when accelerators for this +widget get added, removed or changed. + + + + + + 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 + + + + + + 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 ::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_paintable(). + +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 ::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 +gdk_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 gdk_drag_finish(). + +The handler may inspect the selected action with +gdk_drag_context_get_selected_action() before calling +gdk_drag_finish(), e.g. to implement %GDK_ACTION_ASK as +shown in the following example: +|[<!-- language="C" --> +void +drag_data_received (GtkWidget *widget, + GdkDrop *drop, + GtkSelectionData *data) +{ + if ((data->length >= 0) && (data->format == 8)) + { + GdkDragAction action; + + // handle data here + + action = gdk_drop_get_actions (drop); + if (!gdk_drag_action_is_unique (action)) + { + 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; + } + + gdk_drop_finish (context, action); + } + else + gdk_drop_finish (context, 0); + } +]| + + + + + + the #GdkDrop + + + + where the drop happened + + + + + + 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 gdk_drag_finish() is called to let the source know that +the drop is done. The call to gdk_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 #GdkDrop + + + + the x coordinate of the current cursor position + + + + the y coordinate of the current cursor position + + + + + + 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 ::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, + GdkDrop *drop, + gint x, + gint y, +{ + 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, drop, NULL); + if (target == NULL) + gdk_drop_status (drop, 0); + else + { + private_data->pending_status + = gdk_drop_get_actions (drop); + gtk_drag_get_data (widget, drop, target); + } + + return TRUE; +} + +static void +drag_data_received (GtkWidget *widget, + GdkDrop *drop, + GtkSelectionData *selection_data) +{ + 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_drop_status (drop, 0); + else + gdk_drag_status (drop, GDK_ACTION_ALL); + } + else + { + // accept the drop + } +} +]| + + whether the cursor position is in a drop zone + + + + + the #GdkDrop + + + + the x coordinate of the current cursor position + + + + the y coordinate of the current cursor position + + + + + + 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(). + + + + + + 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 widget(s). + + + + + the direction of movement + + + + + + 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. + +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 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 + + + + + + + + + + + + + + + + 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 + + + + + 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 +#GdkSurface, which means that gtk_widget_realize() has been called or the +widget has been mapped (that is, it is going to be drawn). + + + + + + The ::show signal is emitted when @widget is shown, for example with +gtk_widget_show(). + + + + + + + + + + + the content width of the widget + + + + the content height of the widget + + + + the baseline + + + + + + The ::state-flags-changed signal is emitted when the widget state +changes, see gtk_widget_get_state_flags(). + + + + + + The previous state flags. + + + + + + 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(). + + + + + + 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 ::unrealize signal is 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). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #GtkSizeRequestMode preferred by @widget. + + + + + a #GtkWidget instance + + + + + + + + + + + + + + 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, or %NULL + + + + location to store the natural size, or %NULL + + + + location to store the baseline + position for the minimum size, or %NULL + + + + location to store the baseline + position for the natural size, or %NULL + + + + + + + + + + %TRUE if the signal has been handled + + + + + a #GtkWidget + + + + %TRUE if there are other widgets with the same mnemonic + + + + + + + + + + + + + + a #GtkWidget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %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 #AtkObject associated with @widget + + + + + a #GtkWidget + + + + + + + + + + %TRUE if the accelerator can be activated. + + + + + a #GtkWidget + + + + the ID of a signal installed on @widget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %TRUE if @widget contains (@x, @y). + + + + + the widget to query + + + + X coordinate to test, relative to @widget's origin + + + + Y coordinate to test, relative to @widget's origin + + + + + + + + + + + + + + + + + + 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. + + + + + + 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 + + + + + + Retrieves the type of the #GtkLayoutManager used by the #GtkWidget class. + +See also: gtk_widget_class_set_layout_manager_type() + + + a #GtkLayoutManager subclass, or %G_TYPE_INVALID + + + + + a #GtkWidgetClass + + + + + + 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 + + + + + + Sets the type to be used for creating layout managers for widgets of +@widget_class. The given @type must be a subtype of #GtkLayoutManager. + +This function should only be called from class init functions of widgets. + + + + + + + class to set the layout manager type for + + + + 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, 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 + + + + + + + + + + GtkWidgetPaintable is an implementation of the #GdkPaintable interface +that allows displaying the contents of a #GtkWidget. + +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 #GdkPaintable::invalidate-size signal whenever +the size of the widget changes as well as for visual changes by +emitting the #GdkPaintable::invalidate-contents signal whenever the +widget changes. + +You can of course 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 the #GtkPicture: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 or %NULL + + + + + + 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 or %NULL + + + + + + The observed widget or %NULL if none. + + + + + + + + + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + 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(). + +An example of a UI definition fragment with accel groups: +|[ +<object class="GtkWindow"> + <accel-groups> + <group name="accelgroup1"/> + </accel-groups> +</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 + + + + + + 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. + +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 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_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 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. + + + + + + + a #GtkWindow + + + + mouse button that initiated the drag + + + + X position where the user clicked to initiate the drag, in 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. + + + + + + + a #GtkWindow + + + + position of the resize control + + + + mouse button that initiated the drag + + + + X position where the user clicked to initiate the drag, in 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 #GdkSurface::state property. + + + + + + + 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 iconification via the #GdkSurface::state property + + + + + + + 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 iconification via the #GdkSurface::state property + + + + + + + a #GtkWindow + + + + 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 + + + + + + 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 + + + + + + Returns whether the window will be hidden when the close button is clicked. + + + %TRUE if the window will be hidden + + + + + 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 + + + + + + Gets the value set by gtk_window_set_resizable(). + + + %TRUE if the user can resize the window + + + + + 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" --> + GtkWindow *window = GTK_WINDOW (gtk_window_new (GTK_WINDOW_TOPLEVEL)); + int width = 500; + int height = 300; + 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, + const GtkAllocation *allocation, + int baseline) +{ + 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 + + + + + + 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 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. + + + + + 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 #GdkSurface::state property. + + + + + + + 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. +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 #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 iconification via the #GdkSurface::state property +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 + + + + + + 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 + + + + + + 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 + + + + + + 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 + + + + + + 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. + +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 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 + + + + + + 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. + + + + + + + a #GtkWindow + + + + widget to be the default, or %NULL + to unset the default widget for the toplevel + + + + + + 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 + + + + + + Sets the #GdkDisplay where the @window is displayed; if +the window is already mapped, it will be unmapped, and +then remapped on the new display. + + + + + + + a #GtkWindow. + + + + a #GdkDisplay. + + + + + + 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 + + + + + + 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 clicking the close button on the window +will not destroy it, but only hide it. + + + + + + + a #GtkWindow + + + + whether to hide the window when it is closed + + + + + + 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 iconification via the #GdkSurface::state property + +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 iconification via the #GdkSurface::state property + +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 + + + + + + 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 + + + + + + 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 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. + +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 +positioned relative 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 + + + + + + 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 iconification via the #GdkSurface::state property. + + + + + + + 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 iconification via the #GdkSurface::state property + + + + + + + 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 iconification via the #GdkSurface::state property + + + + + + + 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 stuck. Just don’t write code that crashes if not. + +You can track iconification via the #GdkSurface::state property. + + + + + + + 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 :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. + + + + + + + + + + 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 ::close-request signal is emitted when the user clicks on the close +button of the window. + + %TRUE to stop other handlers from being invoked for the signal + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The parent class. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. 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 + + + + 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 + + + + + + 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 + + + + + + + + + + + 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 + + + + + + Appends the image targets supported by #GtkSelectionData to +the target list. All targets are added with the same @info. + + + + + + + a #GdkContentFormats + + + + whether to add only targets for which GTK+ knows + how to convert a pixbuf into the format + + + + + + Appends the text targets supported by #GtkSelectionData to +the target list. All targets are added with the same @info. + + + + + + + a #GdkContentFormats + + + + + + Appends the URI targets supported by #GtkSelectionData to +the target list. All targets are added with the same @info. + + + + + + + a #GdkContentFormats + + + + + + 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() 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(), 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 drag context, as e.g. returned by gtk_drag_begin() + + + + + + 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 drag context + + + + + + Sets the icon for a particular drag to the default +icon. + + + + + + + the context for 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 + + + + 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 + + + + name of icon to use + + + + the X offset of the hotspot within the icon + + + + the Y offset of the hotspot within the icon + + + + + + Sets @paintable 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 @paintable relative to the mouse, its top +left will be positioned @hot_x, @hot_y pixels from the +mouse cursor. + + + + + + + the context for a drag + + + + the #GdkPaintable to use as icon + + + + the X offset of the hotspot within the icon + + + + the Y offset of the hotspot within the 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 + + + + a widget to use as an icon + + + + the X offset within @widget of the hotspot + + + + the Y offset within @widget of the hotspot + + + + + + Gets a property of the #GtkEditable delegate for @object. + +This is helper function that should be called in get_property, +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 set_property, +before handling your own properties. + + + %TRUE if the property was found + + + + + a #GObject + + + + a property ID + + + + value to set + + + + the #GParamSpec for the property + + + + + + Installs the GtkEditable properties for @class. + +This is a helper function that should be called in class_init, +after installing your own properties. + +To handle the properties in your set_property and get_property +functions, you can either use gtk_editable_delegate_set_property() +and 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 +#GtkEditableProperties 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 + + + + + + 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 + + + + + Registers an error quark for #GtkFileChooser if necessary. + + The error quark used for #GtkFileChooser errors. + + + + + 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 reference 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 reference of the current event, or + %NULL if there is no current event. The returned event must be + freed with g_object_unref(). + + + + + 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 is the deepmost +receiver of the event. + + + the target widget, or %NULL + + + + + a #GdkEvent + + + + + + If @event is %NULL or the event was not associated with any widget, +returns %NULL, otherwise returns first widget found from the event +target to the toplevel that matches @type. + + + the widget in the target stack +with the given type, or %NULL + + + + + a #GdkEvent + + + + the type to look for + + + + + + 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 + + + + + Get the thread from which GTK was initialized. + + + The #GThread initialized for GTK, must not be freed + + + + + 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 + + + + + Queries the current grab of the default window group. + + + The widget which currently + has the grab or %NULL if no grab is active + + + + + 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 + + + + + + + + + + + + + + + + + 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. + +If you are using #GtkApplication, you don't have to call gtk_init() +or gtk_init_check(); 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. + +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. + + + + + + + This function does the same work as 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 + + + + + Use this function to check if GTK has been initialized with gtk_init() +or gtk_init_check(). + + + the initialization status + + + + + 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. + +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. + + + + + + + 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 + + + + + + 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. This function will emit the event +through all the hierarchy of @widget through all propagation phases. + +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 +gtk_widget_queue_draw() instead +of making up expose events. + + + + + + + a #GtkWidget + + + + an event + + + + + + 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 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. + + + + + + + + + + + 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 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 + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + Finds the GtkRoot associated with the surface. + + + the #GtkRoot that is associated with @surface + + + + + a #GdkSurface + + + + + + 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 + + + + + + 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_on_window() 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 + + + + + + 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 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 + + + + + + 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+ and Gdk object types. +This allowes 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 + + + + + + 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 + + + + + + diff --git a/gir-files/GtkSource-3.0.gir b/gir-files/GtkSource-3.0.gir new file mode 100644 index 0000000..4e14517 --- /dev/null +++ b/gir-files/GtkSource-3.0.gir @@ -0,0 +1,13285 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + no pattern + + + grid pattern + + + + + there is no bracket to match. + + + matching a bracket + failed because the maximum range was reached. + + + a matching bracket was not found. + + + a matching bracket was found. + + + + + + Creates a new source buffer. + + + a new source buffer. + + + + + a #GtkTextTagTable, or %NULL to create a new one. + + + + + + Creates a new source buffer using the highlighting patterns in +@language. This is equivalent to creating a new source buffer with +a new tag table and then calling gtk_source_buffer_set_language(). + + + a new source buffer which will highlight text +according to the highlighting patterns in @language. + + + + + a #GtkSourceLanguage. + + + + + + + + + + + + + + + + + + + + + + + Redoes the last undo operation. Use gtk_source_buffer_can_redo() +to check whether a call to this function will have any effect. + +This function emits the #GtkSourceBuffer::redo signal. + + + + + + + a #GtkSourceBuffer. + + + + + + Undoes the last user action which modified the buffer. Use +gtk_source_buffer_can_undo() to check whether a call to this +function will have any effect. + +This function emits the #GtkSourceBuffer::undo signal. + + + + + + + a #GtkSourceBuffer. + + + + + + Moves @iter to the position of the previous #GtkSourceMark of the given +category. Returns %TRUE if @iter was moved. If @category is NULL, the +previous source mark can be of any category. + + + whether @iter was moved. + + + + + a #GtkSourceBuffer. + + + + an iterator. + + + + category to search for, or %NULL + + + + + + Marks the beginning of a not undoable action on the buffer, +disabling the undo manager. Typically you would call this function +before initially setting the contents of the buffer (e.g. when +loading a file in a text editor). + +You may nest gtk_source_buffer_begin_not_undoable_action() / +gtk_source_buffer_end_not_undoable_action() blocks. + + + + + + + a #GtkSourceBuffer. + + + + + + Determines whether a source buffer can redo the last action +(i.e. if the last operation was an undo). + + + %TRUE if a redo is possible. + + + + + a #GtkSourceBuffer. + + + + + + Determines whether a source buffer can undo the last action. + + + %TRUE if it's possible to undo the last action. + + + + + a #GtkSourceBuffer. + + + + + + Changes the case of the text between the specified iterators. + + + + + + + a #GtkSourceBuffer. + + + + how to change the case. + + + + a #GtkTextIter. + + + + a #GtkTextIter. + + + + + + Creates a source mark in the @buffer of category @category. A source mark is +a #GtkTextMark but organised into categories. Depending on the category +a pixbuf can be specified that will be displayed along the line of the mark. + +Like a #GtkTextMark, a #GtkSourceMark can be anonymous if the +passed @name is %NULL. Also, the buffer owns the marks so you +shouldn't unreference it. + +Marks always have left gravity and are moved to the beginning of +the line when the user deletes the line they were in. + +Typical uses for a source mark are bookmarks, breakpoints, current +executing instruction indication in a source file, etc.. + + + a new #GtkSourceMark, owned by the buffer. + + + + + a #GtkSourceBuffer. + + + + the name of the mark, or %NULL. + + + + a string defining the mark category. + + + + location to place the mark. + + + + + + In short, this is the same function as gtk_text_buffer_create_tag(), but +instead of creating a #GtkTextTag, this function creates a #GtkSourceTag. + +This function creates a #GtkSourceTag 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 #GtkSourceTag. + + + + + a #GtkSourceBuffer + + + + name of the new tag, or %NULL + + + + name of first property to set, or %NULL + + + + %NULL-terminated list of property names and values + + + + + + Marks the end of a not undoable action on the buffer. When the +last not undoable block is closed through the call to this +function, the list of undo actions is cleared and the undo manager +is re-enabled. + + + + + + + a #GtkSourceBuffer. + + + + + + Forces buffer to analyze and highlight the given area synchronously. + +<note> + <para> + This is a potentially slow operation and should be used only + when you need to make sure that some text not currently + visible is highlighted, for instance before printing. + </para> +</note> + + + + + + + a #GtkSourceBuffer. + + + + start of the area to highlight. + + + + end of the area to highlight. + + + + + + Moves @iter to the position of the next #GtkSourceMark of the given +@category. Returns %TRUE if @iter was moved. If @category is NULL, the +next source mark can be of any category. + + + whether @iter was moved. + + + + + a #GtkSourceBuffer. + + + + an iterator. + + + + category to search for, or %NULL + + + + + + Get all defined context classes at @iter. + +See the #GtkSourceBuffer description for the list of default context classes. + + + a new %NULL +terminated array of context class names. +Use g_strfreev() to free the array if it is no longer needed. + + + + + + + a #GtkSourceBuffer. + + + + a #GtkTextIter. + + + + + + Determines whether bracket match highlighting is activated for the +source buffer. + + + %TRUE if the source buffer will highlight matching +brackets. + + + + + a #GtkSourceBuffer. + + + + + + Determines whether syntax highlighting is activated in the source +buffer. + + + %TRUE if syntax highlighting is enabled, %FALSE otherwise. + + + + + a #GtkSourceBuffer. + + + + + + + + whether the @buffer has an implicit trailing newline. + + + + + a #GtkSourceBuffer. + + + + + + Returns the #GtkSourceLanguage associated with the buffer, +see gtk_source_buffer_set_language(). The returned object should not be +unreferenced by the user. + + + the #GtkSourceLanguage associated +with the buffer, or %NULL. + + + + + a #GtkSourceBuffer. + + + + + + Determines the number of undo levels the buffer will track for buffer edits. + + + the maximum number of possible undo levels or -1 if no limit is set. + + + + + a #GtkSourceBuffer. + + + + + + Returns the list of marks of the given category at @iter. If @category +is %NULL it returns all marks at @iter. + + + +a newly allocated #GSList. + + + + + + + a #GtkSourceBuffer. + + + + an iterator. + + + + category to search for, or %NULL + + + + + + Returns the list of marks of the given category at @line. +If @category is %NULL, all marks at @line are returned. + + + +a newly allocated #GSList. + + + + + + + a #GtkSourceBuffer. + + + + a line number. + + + + category to search for, or %NULL + + + + + + Returns the #GtkSourceStyleScheme associated with the buffer, +see gtk_source_buffer_set_style_scheme(). +The returned object should not be unreferenced by the user. + + + the #GtkSourceStyleScheme +associated with the buffer, or %NULL. + + + + + a #GtkSourceBuffer. + + + + + + Returns the #GtkSourceUndoManager associated with the buffer, +see gtk_source_buffer_set_undo_manager(). The returned object should not be +unreferenced by the user. + + + the #GtkSourceUndoManager associated +with the buffer, or %NULL. + + + + + a #GtkSourceBuffer. + + + + + + Moves backward to the next toggle (on or off) of the context class. If no +matching context class 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. + +See the #GtkSourceBuffer description for the list of default context classes. + + + whether we found a context class toggle before @iter + + + + + a #GtkSourceBuffer. + + + + a #GtkTextIter. + + + + the context class. + + + + + + Moves forward to the next toggle (on or off) of the context class. If no +matching context class 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. + +See the #GtkSourceBuffer description for the list of default context classes. + + + whether we found a context class toggle after @iter + + + + + a #GtkSourceBuffer. + + + + a #GtkTextIter. + + + + the context class. + + + + + + Check if the class @context_class is set on @iter. + +See the #GtkSourceBuffer description for the list of default context classes. + + + whether @iter has the context class. + + + + + a #GtkSourceBuffer. + + + + a #GtkTextIter. + + + + class to search for. + + + + + + Joins the lines of text between the specified iterators. + + + + + + + a #GtkSourceBuffer. + + + + a #GtkTextIter. + + + + a #GtkTextIter. + + + + + + Redoes the last undo operation. Use gtk_source_buffer_can_redo() +to check whether a call to this function will have any effect. + +This function emits the #GtkSourceBuffer::redo signal. + + + + + + + a #GtkSourceBuffer. + + + + + + Remove all marks of @category between @start and @end from the buffer. +If @category is NULL, all marks in the range will be removed. + + + + + + + a #GtkSourceBuffer. + + + + a #GtkTextIter. + + + + a #GtkTextIter. + + + + category to search for, or %NULL. + + + + + + Controls the bracket match highlighting function in the buffer. If +activated, when you position your cursor over a bracket character +(a parenthesis, a square bracket, etc.) the matching opening or +closing bracket character will be highlighted. + + + + + + + a #GtkSourceBuffer. + + + + %TRUE if you want matching brackets highlighted. + + + + + + Controls whether syntax is highlighted in the buffer. + +If @highlight is %TRUE, the text will be highlighted according to the syntax +patterns specified in the #GtkSourceLanguage set with +gtk_source_buffer_set_language(). + +If @highlight is %FALSE, syntax highlighting is disabled and all the +#GtkTextTag objects that have been added by the syntax highlighting engine +are removed from the buffer. + + + + + + + a #GtkSourceBuffer. + + + + %TRUE to enable syntax highlighting, %FALSE to disable it. + + + + + + Sets whether the @buffer has an implicit trailing newline. + +If an explicit trailing newline is present in a #GtkTextBuffer, #GtkTextView +shows it as an empty line. This is generally not what the user expects. + +If @implicit_trailing_newline is %TRUE (the default value): + - when a #GtkSourceFileLoader loads the content of a file into the @buffer, + the trailing newline (if present in the file) is not inserted into the + @buffer. + - when a #GtkSourceFileSaver saves the content of the @buffer into a file, a + trailing newline is added to the file. + +On the other hand, if @implicit_trailing_newline is %FALSE, the file's +content is not modified when loaded into the @buffer, and the @buffer's +content is not modified when saved into a file. + + + + + + + a #GtkSourceBuffer. + + + + the new value. + + + + + + Associates a #GtkSourceLanguage with the buffer. + +Note that a #GtkSourceLanguage affects not only the syntax highlighting, but +also the [context classes][context-classes]. If you want to disable just the +syntax highlighting, see gtk_source_buffer_set_highlight_syntax(). + +The buffer holds a reference to @language. + + + + + + + a #GtkSourceBuffer. + + + + a #GtkSourceLanguage to set, or %NULL. + + + + + + Sets the number of undo levels for user actions the buffer will +track. If the number of user actions exceeds the limit set by this +function, older actions will be discarded. + +If @max_undo_levels is -1, the undo/redo is unlimited. + +If @max_undo_levels is 0, the undo/redo is disabled. + + + + + + + a #GtkSourceBuffer. + + + + the desired maximum number of undo levels. + + + + + + Sets a #GtkSourceStyleScheme to be used by the buffer and the view. + +Note that a #GtkSourceStyleScheme affects not only the syntax highlighting, +but also other #GtkSourceView features such as highlighting the current line, +matching brackets, the line numbers, etc. + +Instead of setting a %NULL @scheme, it is better to disable syntax +highlighting with gtk_source_buffer_set_highlight_syntax(), and setting the +#GtkSourceStyleScheme with the "classic" or "tango" ID, because those two +style schemes follow more closely the GTK+ theme (for example for the +background color). + +The buffer holds a reference to @scheme. + + + + + + + a #GtkSourceBuffer. + + + + a #GtkSourceStyleScheme or %NULL. + + + + + + Set the buffer undo manager. If @manager is %NULL the default undo manager +will be set. + + + + + + + a #GtkSourceBuffer. + + + + A #GtkSourceUndoManager or %NULL. + + + + + + Sort the lines of text between the specified iterators. + + + + + + + a #GtkSourceBuffer. + + + + a #GtkTextIter. + + + + a #GtkTextIter. + + + + #GtkSourceSortFlags specifying how the sort should behave + + + + sort considering the text starting at the given column + + + + + + Undoes the last user action which modified the buffer. Use +gtk_source_buffer_can_undo() to check whether a call to this +function will have any effect. + +This function emits the #GtkSourceBuffer::undo signal. + + + + + + + a #GtkSourceBuffer. + + + + + + + + + + + + Whether to highlight matching brackets in the buffer. + + + + Whether to highlight syntax in the buffer. + + + + Whether the buffer has an implicit trailing newline. See +gtk_source_buffer_set_implicit_trailing_newline(). + + + + + + + Number of undo levels for the buffer. -1 means no limit. This property +will only affect the default undo manager. + + + + Style scheme. It contains styles for syntax highlighting, optionally +foreground, background, cursor color, current line color, and matching +brackets style. + + + + + + + + + + + + + @iter is set to a valid iterator pointing to the matching bracket +if @state is %GTK_SOURCE_BRACKET_MATCH_FOUND. Otherwise @iter is +meaningless. + +The signal is emitted only when the @state changes, typically when +the cursor moves. + +A use-case for this signal is to show messages in a #GtkStatusbar. + + + + + + if found, the location of the matching bracket. + + + + state of bracket matching. + + + + + + The ::highlight-updated signal is emitted when the syntax +highlighting and [context classes][context-classes] are updated in a +certain region of the @buffer. + + + + + + the start of the updated region + + + + the end of the updated region + + + + + + The ::redo signal is emitted to redo the last undo operation. + + + + + + The ::source-mark-updated signal is emitted each time +a mark is added to, moved or removed from the @buffer. + + + + + + the #GtkSourceMark + + + + + + The ::undo signal is emitted to undo the last user action which +modified the buffer. + + + + + + + + + + + + + + + + + + + a #GtkSourceBuffer. + + + + + + + + + + + + + + a #GtkSourceBuffer. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + change case to lowercase. + + + change case to uppercase. + + + toggle case of each character. + + + capitalize each word. + + + + + + + + + + + + + + + + + + Hides the completion if it is active (visible). + + + + + + + a #GtkSourceCompletion. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Add a new #GtkSourceCompletionProvider to the completion object. This will +add a reference @provider, so make sure to unref your own copy when you +no longer need it. + + + %TRUE if @provider was successfully added, otherwise if @error + is provided, it will be set with the error and %FALSE is returned. + + + + + a #GtkSourceCompletion. + + + + a #GtkSourceCompletionProvider. + + + + + + Block interactive completion. This can be used to disable interactive +completion when inserting or deleting text from the buffer associated with +the completion. Use gtk_source_completion_unblock_interactive() to enable +interactive completion again. + +This function may be called multiple times. It will continue to block +interactive completion until gtk_source_completion_unblock_interactive() +has been called the same number of times. + + + + + + + a #GtkSourceCompletion. + + + + + + Create a new #GtkSourceCompletionContext for @completion. The position where +the completion occurs can be specified by @position. If @position is %NULL, +the current cursor position will be used. + + + a new #GtkSourceCompletionContext. +The reference being returned is a 'floating' reference, +so if you invoke gtk_source_completion_show() with this context +you don't need to unref it. + + + + + a #GtkSourceCompletion. + + + + a #GtkTextIter, or %NULL. + + + + + + The info widget is the window where the completion displays optional extra +information of the proposal. + + + The #GtkSourceCompletionInfo window + associated with @completion. + + + + + a #GtkSourceCompletion. + + + + + + Get list of providers registered on @completion. The returned list is owned +by the completion and should not be freed. + + + +list of #GtkSourceCompletionProvider. + + + + + + + a #GtkSourceCompletion. + + + + + + The #GtkSourceView associated with @completion, or %NULL if the view has been +destroyed. + + + The #GtkSourceView associated with +@completion, or %NULL. + + + + + a #GtkSourceCompletion. + + + + + + Hides the completion if it is active (visible). + + + + + + + a #GtkSourceCompletion. + + + + + + Move the completion window to a specific iter. + Use gtk_source_completion_provider_get_start_iter() instead. + + + + + + + a #GtkSourceCompletion. + + + + a #GtkTextIter. + + + + + + Remove @provider from the completion. + + + %TRUE if @provider was successfully removed, otherwise if @error + is provided, it will be set with the error and %FALSE is returned. + + + + + a #GtkSourceCompletion. + + + + a #GtkSourceCompletionProvider. + + + + + + Starts a new completion with the specified #GtkSourceCompletionContext and +a list of potential candidate providers for completion. + +It can be convenient for showing a completion on-the-fly, without the need to +add or remove providers to the #GtkSourceCompletion. + +Another solution is to add providers with +gtk_source_completion_add_provider(), and implement +gtk_source_completion_provider_match() for each provider. + + + %TRUE if it was possible to the show completion window. + + + + + a #GtkSourceCompletion. + + + + +a list of #GtkSourceCompletionProvider, or %NULL. + + + + + + The #GtkSourceCompletionContext +with which to start the completion. + + + + + + Unblock interactive completion. This can be used after using +gtk_source_completion_block_interactive() to enable interactive completion +again. + + + + + + + a #GtkSourceCompletion. + + + + + + Number of keyboard accelerators to show for the first proposals. For +example, to activate the first proposal, the user can press +<keycombo><keycap>Alt</keycap><keycap>1</keycap></keycombo>. + + + + Determines the popup delay (in milliseconds) at which the completion +will be shown for interactive completion. + + + + The scroll page size of the proposals in the completion window. In +other words, when <keycap>PageDown</keycap> or +<keycap>PageUp</keycap> is pressed, the selected +proposal becomes the one which is located one page size backward or +forward. + +See also the #GtkSourceCompletion::move-cursor signal. + + + + The scroll page size of the provider pages in the completion window. + +See the #GtkSourceCompletion::move-page signal. + + + + Determines whether the visibility of the info window should be +saved when the completion is hidden, and restored when the completion +is shown again. + + + + Determines whether the first proposal should be selected when the +completion is first shown. + + + + Determines whether provider headers should be shown in the proposal +list. It can be useful to disable when there is only one provider. + + + + Determines whether provider and proposal icons should be shown in +the completion popup. + + + + The #GtkSourceView bound to the completion object. + + + + + + + + + + The #GtkSourceCompletion::activate-proposal signal is a +keybinding signal which gets emitted when the user initiates +a proposal activation. + +Applications should not connect to it, but may emit it with +g_signal_emit_by_name() if they need to control the proposal +activation programmatically. + + + + + + Emitted when the completion window is hidden. The default handler +will actually hide the window. + + + + + + The #GtkSourceCompletion::move-cursor signal is a keybinding +signal which gets emitted when the user initiates a cursor +movement. + +The <keycap>Up</keycap>, <keycap>Down</keycap>, +<keycap>PageUp</keycap>, <keycap>PageDown</keycap>, +<keycap>Home</keycap> and <keycap>End</keycap> keys are bound to the +normal behavior expected by those keys. + +When @step is equal to %GTK_SCROLL_PAGES, the page size is defined by +the #GtkSourceCompletion:proposal-page-size property. It is used for +the <keycap>PageDown</keycap> and <keycap>PageUp</keycap> 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. + + + + + + The #GtkScrollStep by which to move the cursor + + + + The amount of steps to move the cursor + + + + + + The #GtkSourceCompletion::move-page signal is a keybinding +signal which gets emitted when the user initiates a page +movement (i.e. switches between provider pages). + +<keycombo><keycap>Control</keycap><keycap>Left</keycap></keycombo> +is for going to the previous provider. +<keycombo><keycap>Control</keycap><keycap>Right</keycap></keycombo> +is for going to the next provider. +<keycombo><keycap>Control</keycap><keycap>Home</keycap></keycombo> +is for displaying all the providers. +<keycombo><keycap>Control</keycap><keycap>End</keycap></keycombo> +is for going to the last provider. + +When @step is equal to #GTK_SCROLL_PAGES, the page size is defined by +the #GtkSourceCompletion:provider-page-size property. + +Applications should not connect to it, but may emit it with +g_signal_emit_by_name() if they need to control the page selection +programmatically. + + + + + + The #GtkScrollStep by which to move the page + + + + The amount of steps to move the page + + + + + + Emitted just before starting to populate the completion with providers. +You can use this signal to add additional attributes in the context. + + + + + + The #GtkSourceCompletionContext for the current completion + + + + + + Emitted when the completion window is shown. The default handler +will actually show the window. + + + + + + + + None. + + + Interactive activation. By +default, it occurs on each insertion in the #GtkTextBuffer. This can be +blocked temporarily with gtk_source_completion_block_interactive(). + + + User requested activation. +By default, it occurs when the user presses +<keycombo><keycap>Control</keycap><keycap>space</keycap></keycombo>. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GtkSourceCompletion. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Providers can use this function to add proposals to the completion. They +can do so asynchronously by means of the @finished argument. Providers must +ensure that they always call this function with @finished set to %TRUE +once each population (even if no proposals need to be added). +Population occurs when the gtk_source_completion_provider_populate() +function is called. + + + + + + + a #GtkSourceCompletionContext. + + + + a #GtkSourceCompletionProvider. + + + + The list of proposals to add. + + + + + + Whether the provider is finished adding proposals. + + + + + + Get the context activation. + + + The context activation. + + + + + a #GtkSourceCompletionContext. + + + + + + Get the iter at which the completion was invoked. Providers can use this +to determine how and if to match proposals. + + + %TRUE if @iter is correctly set, %FALSE otherwise. + + + + + a #GtkSourceCompletionContext. + + + + a #GtkTextIter. + + + + + + The completion activation + + + + The #GtkSourceCompletion associated with the context. + + + + The #GtkTextIter at which the completion is invoked. + + + + + + + + + + Emitted when the current population of proposals has been cancelled. +Providers adding proposals asynchronously should connect to this signal +to know when to cancel running proposal queries. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + An error code used with %GTK_SOURCE_COMPLETION_ERROR in a #GError returned +from a completion-related function. + + The #GtkSourceCompletionProvider +is already bound to the #GtkSourceCompletion object. + + + The #GtkSourceCompletionProvider is +not bound to the #GtkSourceCompletion object. + + + + + + + + + + + + + + + a new GtkSourceCompletionInfo. + + + + + + + + + + + + + + + + Get the current content widget. + Use gtk_bin_get_child() instead. + + + The current content widget. + + + + + a #GtkSourceCompletionInfo. + + + + + + Moves the #GtkSourceCompletionInfo to @iter. If @iter is %NULL @info is +moved to the cursor position. Moving will respect the #GdkGravity setting +of the info window and will ensure the line at @iter is not occluded by +the window. + + + + + + + a #GtkSourceCompletionInfo. + + + + a #GtkTextView on which the info window should be positioned. + + + + a #GtkTextIter. + + + + + + Sets the content widget of the info window. See that the previous widget will +lose a reference and it can be destroyed, so if you do not want this to +happen you must use g_object_ref() before calling this method. + Use gtk_container_add() instead. If there is already a child +widget, remove it with gtk_container_remove(). + + + + + + + a #GtkSourceCompletionInfo. + + + + a #GtkWidget. + + + + + + + + + + + + This signal is emitted before any "show" management. You can connect +to this signal if you want to change some properties or position +before the real "show". + This signal should not be used. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Create a new #GtkSourceCompletionItem with label @label, icon @icon and +extra information @info. Both @icon and @info can be %NULL in which case +there will be no icon shown and no extra information available. + Use gtk_source_completion_item_new2() instead. + + + a new #GtkSourceCompletionItem. + + + + + The item label. + + + + The item text. + + + + The item icon. + + + + The item extra information. + + + + + + Creates a new #GtkSourceCompletionItem from a stock item. If @label is %NULL, +the stock label will be used. + Use gtk_source_completion_item_new2() instead. + + + a new #GtkSourceCompletionItem. + + + + + The item label. + + + + The item text. + + + + The stock icon. + + + + The item extra information. + + + + + + Create a new #GtkSourceCompletionItem with markup label @markup, icon +@icon and extra information @info. Both @icon and @info can be %NULL in +which case there will be no icon shown and no extra information available. + Use gtk_source_completion_item_new2() instead. + + + a new #GtkSourceCompletionItem. + + + + + The item markup label. + + + + The item text. + + + + The item icon. + + + + The item extra information. + + + + + + Creates a new #GtkSourceCompletionItem. The desired properties need to be set +afterwards. + + + a new #GtkSourceCompletionItem. + + + + + + + + + + + a #GtkSourceCompletionItem. + + + + the #GIcon, or %NULL. + + + + + + + + + + + + a #GtkSourceCompletionItem. + + + + the #GdkPixbuf, or %NULL. + + + + + + + + + + + + a #GtkSourceCompletionItem. + + + + the icon name, or %NULL. + + + + + + + + + + + + a #GtkSourceCompletionItem. + + + + the info, or %NULL. + + + + + + + + + + + + a #GtkSourceCompletionItem. + + + + the label, or %NULL. + + + + + + + + + + + + a #GtkSourceCompletionItem. + + + + the markup, or %NULL. + + + + + + + + + + + + a #GtkSourceCompletionItem. + + + + the text, or %NULL. + + + + + + The #GIcon for the icon to be shown for this proposal. + + + + The #GdkPixbuf for the icon to be shown for this proposal. + + + + The icon name for the icon to be shown for this proposal. + + + + Optional extra information to be shown for this proposal. + + + + Label to be shown for this proposal. + + + + Label with markup to be shown for this proposal. + + + + Proposal text. + + + + + + + + + + + + + + + + + + + + + + + + + Emits the "changed" signal on @proposal. This should be called by +implementations whenever the name, icon or info of the proposal has +changed. + + + + + + + a #GtkSourceCompletionProposal. + + + + + + Get whether two proposal objects are the same. This is used to (together +with gtk_source_completion_proposal_hash()) to match proposals in the +completion model. By default, it uses direct equality (g_direct_equal()). + + + %TRUE if @proposal and @object are the same proposal + + + + + a #GtkSourceCompletionProposal. + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the #GIcon for the icon of @proposal. + + + A #GIcon with the icon of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the #GdkPixbuf for the icon of @proposal. + + + A #GdkPixbuf with the icon of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the icon name of @proposal. + + + The icon name of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets extra information associated to the proposal. This information will be +used to present the user with extra, detailed information about the +selected proposal. The returned string must be freed with g_free(). + + + a newly-allocated string containing +extra information of @proposal or %NULL if no extra information is associated +to @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the label of @proposal. The label is shown in the list of proposals as +plain text. If you need any markup (such as bold or italic text), you have +to implement gtk_source_completion_proposal_get_markup(). The returned string +must be freed with g_free(). + + + a new string containing the label of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the label of @proposal with markup. The label is shown in the list of +proposals and may contain markup. This will be used instead of +gtk_source_completion_proposal_get_label() if implemented. The returned string +must be freed with g_free(). + + + a new string containing the label of @proposal with markup. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the text of @proposal. The text that is inserted into +the text buffer when the proposal is activated by the default activation. +You are free to implement a custom activation handler in the provider and +not implement this function. For more information, see +gtk_source_completion_provider_activate_proposal(). The returned string must +be freed with g_free(). + + + a new string containing the text of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Get the hash value of @proposal. This is used to (together with +gtk_source_completion_proposal_equal()) to match proposals in the completion +model. By default, it uses a direct hash (g_direct_hash()). + + + The hash value of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Emits the "changed" signal on @proposal. This should be called by +implementations whenever the name, icon or info of the proposal has +changed. + + + + + + + a #GtkSourceCompletionProposal. + + + + + + Get whether two proposal objects are the same. This is used to (together +with gtk_source_completion_proposal_hash()) to match proposals in the +completion model. By default, it uses direct equality (g_direct_equal()). + + + %TRUE if @proposal and @object are the same proposal + + + + + a #GtkSourceCompletionProposal. + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the #GIcon for the icon of @proposal. + + + A #GIcon with the icon of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the #GdkPixbuf for the icon of @proposal. + + + A #GdkPixbuf with the icon of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the icon name of @proposal. + + + The icon name of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets extra information associated to the proposal. This information will be +used to present the user with extra, detailed information about the +selected proposal. The returned string must be freed with g_free(). + + + a newly-allocated string containing +extra information of @proposal or %NULL if no extra information is associated +to @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the label of @proposal. The label is shown in the list of proposals as +plain text. If you need any markup (such as bold or italic text), you have +to implement gtk_source_completion_proposal_get_markup(). The returned string +must be freed with g_free(). + + + a new string containing the label of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the label of @proposal with markup. The label is shown in the list of +proposals and may contain markup. This will be used instead of +gtk_source_completion_proposal_get_label() if implemented. The returned string +must be freed with g_free(). + + + a new string containing the label of @proposal with markup. + + + + + a #GtkSourceCompletionProposal. + + + + + + Gets the text of @proposal. The text that is inserted into +the text buffer when the proposal is activated by the default activation. +You are free to implement a custom activation handler in the provider and +not implement this function. For more information, see +gtk_source_completion_provider_activate_proposal(). The returned string must +be freed with g_free(). + + + a new string containing the text of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Get the hash value of @proposal. This is used to (together with +gtk_source_completion_proposal_equal()) to match proposals in the completion +model. By default, it uses a direct hash (g_direct_hash()). + + + The hash value of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + Emitted when the proposal has changed. The completion popup +will react to this by updating the shown information. + + + + + + + The virtual function table for #GtkSourceCompletionProposal. + + + The parent interface. + + + + + + + a new string containing the label of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + a new string containing the label of @proposal with markup. + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + a new string containing the text of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + A #GdkPixbuf with the icon of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + The icon name of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + A #GIcon with the icon of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + a newly-allocated string containing +extra information of @proposal or %NULL if no extra information is associated +to @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + The hash value of @proposal. + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + %TRUE if @proposal and @object are the same proposal + + + + + a #GtkSourceCompletionProposal. + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + + + + + a #GtkSourceCompletionProposal. + + + + + + + + + + Activate @proposal at @iter. When this functions returns %FALSE, the default +activation of @proposal will take place which replaces the word at @iter +with the text of @proposal (see gtk_source_completion_proposal_get_text()). + +Here is how the default activation selects the boundaries of the word to +replace. The end of the word is @iter. For the start of the word, it depends +on whether a start iter is defined for @proposal (see +gtk_source_completion_provider_get_start_iter()). If a start iter is defined, +the start of the word is the start iter. Else, the word (as long as possible) +will contain only alphanumerical and the "_" characters. + + + %TRUE to indicate that the proposal activation has been handled, + %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkTextIter. + + + + + + Get with what kind of activation the provider should be activated. + + + a combination of #GtkSourceCompletionActivation. + + + + + a #GtkSourceCompletionProvider. + + + + + + Gets the #GIcon for the icon of @provider. + + + The icon to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + Get the #GdkPixbuf for the icon of the @provider. + + + The icon to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + Gets the icon name of @provider. + + + The icon name to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + Get a customized info widget to show extra information of a proposal. +This allows for customized widgets on a proposal basis, although in general +providers will have the same custom widget for all their proposals and +@proposal can be ignored. The implementation of this function is optional. + +If this function is not implemented, the default widget is a #GtkLabel. The +return value of gtk_source_completion_proposal_get_info() is used as the +content of the #GtkLabel. + +<note> + <para> + If implemented, gtk_source_completion_provider_update_info() + <emphasis>must</emphasis> also be implemented. + </para> +</note> + + + a custom #GtkWidget to show extra +information about @proposal, or %NULL if the provider does not have a special +info widget. + + + + + a #GtkSourceCompletionProvider. + + + + a currently selected #GtkSourceCompletionProposal. + + + + + + Get the delay in milliseconds before starting interactive completion for +this provider. A value of -1 indicates to use the default value as set +by the #GtkSourceCompletion:auto-complete-delay property. + + + the interactive delay in milliseconds. + + + + + a #GtkSourceCompletionProvider. + + + + + + Get the name of the provider. This should be a translatable name for +display to the user. For example: _("Document word completion provider"). The +returned string must be freed with g_free(). + + + a new string containing the name of the provider. + + + + + a #GtkSourceCompletionProvider. + + + + + + Get the provider priority. The priority determines the order in which +proposals appear in the completion popup. Higher priorities are sorted +before lower priorities. The default priority is 0. + + + the provider priority. + + + + + a #GtkSourceCompletionProvider. + + + + + + Get the #GtkTextIter at which the completion for @proposal starts. When +implemented, this information is used to position the completion window +accordingly when a proposal is selected in the completion window. The +@proposal text inside the completion window is aligned on @iter. + +If this function is not implemented, the word boundary is taken to position +the completion window. See gtk_source_completion_provider_activate_proposal() +for an explanation on the word boundaries. + +When the @proposal is activated, the default handler uses @iter as the start +of the word to replace. See +gtk_source_completion_provider_activate_proposal() for more information. + + + %TRUE if @iter was set for @proposal, %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkTextIter. + + + + + + Get whether the provider match the context of completion detailed in +@context. + + + %TRUE if @provider matches the completion context, %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + + + Populate @context with proposals from @provider added with the +gtk_source_completion_context_add_proposals() function. + + + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + + + Update extra information shown in @info for @proposal. + +<note> + <para> + This function <emphasis>must</emphasis> be implemented when + gtk_source_completion_provider_get_info_widget() is implemented. + </para> +</note> + + + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkSourceCompletionInfo. + + + + + + Activate @proposal at @iter. When this functions returns %FALSE, the default +activation of @proposal will take place which replaces the word at @iter +with the text of @proposal (see gtk_source_completion_proposal_get_text()). + +Here is how the default activation selects the boundaries of the word to +replace. The end of the word is @iter. For the start of the word, it depends +on whether a start iter is defined for @proposal (see +gtk_source_completion_provider_get_start_iter()). If a start iter is defined, +the start of the word is the start iter. Else, the word (as long as possible) +will contain only alphanumerical and the "_" characters. + + + %TRUE to indicate that the proposal activation has been handled, + %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkTextIter. + + + + + + Get with what kind of activation the provider should be activated. + + + a combination of #GtkSourceCompletionActivation. + + + + + a #GtkSourceCompletionProvider. + + + + + + Gets the #GIcon for the icon of @provider. + + + The icon to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + Get the #GdkPixbuf for the icon of the @provider. + + + The icon to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + Gets the icon name of @provider. + + + The icon name to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + Get a customized info widget to show extra information of a proposal. +This allows for customized widgets on a proposal basis, although in general +providers will have the same custom widget for all their proposals and +@proposal can be ignored. The implementation of this function is optional. + +If this function is not implemented, the default widget is a #GtkLabel. The +return value of gtk_source_completion_proposal_get_info() is used as the +content of the #GtkLabel. + +<note> + <para> + If implemented, gtk_source_completion_provider_update_info() + <emphasis>must</emphasis> also be implemented. + </para> +</note> + + + a custom #GtkWidget to show extra +information about @proposal, or %NULL if the provider does not have a special +info widget. + + + + + a #GtkSourceCompletionProvider. + + + + a currently selected #GtkSourceCompletionProposal. + + + + + + Get the delay in milliseconds before starting interactive completion for +this provider. A value of -1 indicates to use the default value as set +by the #GtkSourceCompletion:auto-complete-delay property. + + + the interactive delay in milliseconds. + + + + + a #GtkSourceCompletionProvider. + + + + + + Get the name of the provider. This should be a translatable name for +display to the user. For example: _("Document word completion provider"). The +returned string must be freed with g_free(). + + + a new string containing the name of the provider. + + + + + a #GtkSourceCompletionProvider. + + + + + + Get the provider priority. The priority determines the order in which +proposals appear in the completion popup. Higher priorities are sorted +before lower priorities. The default priority is 0. + + + the provider priority. + + + + + a #GtkSourceCompletionProvider. + + + + + + Get the #GtkTextIter at which the completion for @proposal starts. When +implemented, this information is used to position the completion window +accordingly when a proposal is selected in the completion window. The +@proposal text inside the completion window is aligned on @iter. + +If this function is not implemented, the word boundary is taken to position +the completion window. See gtk_source_completion_provider_activate_proposal() +for an explanation on the word boundaries. + +When the @proposal is activated, the default handler uses @iter as the start +of the word to replace. See +gtk_source_completion_provider_activate_proposal() for more information. + + + %TRUE if @iter was set for @proposal, %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkTextIter. + + + + + + Get whether the provider match the context of completion detailed in +@context. + + + %TRUE if @provider matches the completion context, %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + + + Populate @context with proposals from @provider added with the +gtk_source_completion_context_add_proposals() function. + + + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + + + Update extra information shown in @info for @proposal. + +<note> + <para> + This function <emphasis>must</emphasis> be implemented when + gtk_source_completion_provider_get_info_widget() is implemented. + </para> +</note> + + + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkSourceCompletionInfo. + + + + + + + The virtual function table for #GtkSourceCompletionProvider. + + + The parent interface. + + + + + + + a new string containing the name of the provider. + + + + + a #GtkSourceCompletionProvider. + + + + + + + + + + The icon to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + + + + + The icon name to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + + + + + The icon to be used for the provider, + or %NULL if the provider does not have a special icon. + + + + + The #GtkSourceCompletionProvider + + + + + + + + + + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + + + + + + + %TRUE if @provider matches the completion context, %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + + + + + + + a combination of #GtkSourceCompletionActivation. + + + + + a #GtkSourceCompletionProvider. + + + + + + + + + + a custom #GtkWidget to show extra +information about @proposal, or %NULL if the provider does not have a special +info widget. + + + + + a #GtkSourceCompletionProvider. + + + + a currently selected #GtkSourceCompletionProposal. + + + + + + + + + + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkSourceCompletionInfo. + + + + + + + + + + %TRUE if @iter was set for @proposal, %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionContext. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkTextIter. + + + + + + + + + + %TRUE to indicate that the proposal activation has been handled, + %FALSE otherwise. + + + + + a #GtkSourceCompletionProvider. + + + + a #GtkSourceCompletionProposal. + + + + a #GtkTextIter. + + + + + + + + + + the interactive delay in milliseconds. + + + + + a #GtkSourceCompletionProvider. + + + + + + + + + + the provider priority. + + + + + a #GtkSourceCompletionProvider. + + + + + + + + + + + + + a new #GtkSourceCompletionWords provider + + + + + The name for the provider, or %NULL. + + + + A specific icon for the provider, or %NULL. + + + + + + Registers @buffer in the @words provider. + + + + + + + a #GtkSourceCompletionWords + + + + a #GtkTextBuffer + + + + + + Unregisters @buffer from the @words provider. + + + + + + + a #GtkSourceCompletionWords + + + + a #GtkTextBuffer + + + + + + The type of activation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + plain text. + + + gzip compression. + + + + GtkSourceDrawSpacesFlags determine what kind of spaces whould be drawn. If none +of GTK_SOURCE_DRAW_SPACES_LEADING, GTK_SOURCE_DRAW_SPACES_TEXT or +GTK_SOURCE_DRAW_SPACES_TRAILING is specified, whitespaces at any position in +the line will be drawn (i.e. it has the same effect as specifying all of them). + Use #GtkSourceSpaceTypeFlags and +#GtkSourceSpaceLocationFlags instead. + + whether the space character should be drawn. + + + whether the tab character should be drawn. + + + whether the line breaks should be drawn. If + the #GtkSourceBuffer:implicit-trailing-newline property is %TRUE, a line + break is also drawn at the end of the buffer. + + + whether the non-breaking whitespaces should be drawn. + + + whether leading whitespaces should be drawn. + + + whether whitespaces inside text should be drawn. + + + whether trailing whitespaces should be drawn. + + + wheter all kind of spaces should be drawn. + + + + + + Used by language bindings. + + + a copy of @enc. + + + + + a #GtkSourceEncoding. + + + + + + Used by language bindings. + + + + + + + a #GtkSourceEncoding. + + + + + + Gets the character set of the #GtkSourceEncoding, such as "UTF-8" or +"ISO-8859-1". + + + the character set of the #GtkSourceEncoding. + + + + + a #GtkSourceEncoding. + + + + + + Gets the name of the #GtkSourceEncoding such as "Unicode" or "Western". + + + the name of the #GtkSourceEncoding. + + + + + a #GtkSourceEncoding. + + + + + + + + a string representation. Free with g_free() when no longer needed. + + + + + a #GtkSourceEncoding. + + + + + + Gets all encodings. + + + a list of +all #GtkSourceEncoding's. Free with g_slist_free(). + + + + + + + Gets the #GtkSourceEncoding for the current locale. See also g_get_charset(). + + + the current locale encoding. + + + + + Gets the list of default candidate encodings to try when loading a file. See +gtk_source_file_loader_set_candidate_encodings(). + +This function returns a different list depending on the current locale (i.e. +language, country and default encoding). The UTF-8 encoding and the current +locale encoding are guaranteed to be present in the returned list. + + + the list of +default candidate encodings. Free with g_slist_free(). + + + + + + + Gets a #GtkSourceEncoding from a character set such as "UTF-8" or +"ISO-8859-1". + + + the corresponding #GtkSourceEncoding, or %NULL +if not found. + + + + + a character set. + + + + + + + + the UTF-8 encoding. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a new #GtkSourceFile object. + + + + + Checks synchronously the file on disk, to know whether the file is externally +modified, or has been deleted, and whether the file is read-only. + +#GtkSourceFile doesn't create a #GFileMonitor to track those properties, so +this function needs to be called instead. Creating lots of #GFileMonitor's +would take lots of resources. + +Since this function is synchronous, it is advised to call it only on local +files. See gtk_source_file_is_local(). + + + + + + + a #GtkSourceFile. + + + + + + + + the compression type. + + + + + a #GtkSourceFile. + + + + + + The encoding is initially %NULL. After a successful file loading or saving +operation, the encoding is non-%NULL. + + + the character encoding. + + + + + a #GtkSourceFile. + + + + + + + + the #GFile. + + + + + a #GtkSourceFile. + + + + + + + + the newline type. + + + + + a #GtkSourceFile. + + + + + + Returns whether the file has been deleted. If the +#GtkSourceFile:location is %NULL, returns %FALSE. + +To have an up-to-date value, you must first call +gtk_source_file_check_file_on_disk(). + + + whether the file has been deleted. + + + + + a #GtkSourceFile. + + + + + + Returns whether the file is externally modified. If the +#GtkSourceFile:location is %NULL, returns %FALSE. + +To have an up-to-date value, you must first call +gtk_source_file_check_file_on_disk(). + + + whether the file is externally modified. + + + + + a #GtkSourceFile. + + + + + + Returns whether the file is local. If the #GtkSourceFile:location is %NULL, +returns %FALSE. + + + whether the file is local. + + + + + a #GtkSourceFile. + + + + + + Returns whether the file is read-only. If the +#GtkSourceFile:location is %NULL, returns %FALSE. + +To have an up-to-date value, you must first call +gtk_source_file_check_file_on_disk(). + + + whether the file is read-only. + + + + + a #GtkSourceFile. + + + + + + Sets the location. + + + + + + + a #GtkSourceFile. + + + + the new #GFile, or %NULL. + + + + + + Sets a #GtkSourceMountOperationFactory function that will be called when a +#GMountOperation must be created. This is useful for creating a +#GtkMountOperation with the parent #GtkWindow. + +If a mount operation factory isn't set, g_mount_operation_new() will be +called. + + + + + + + a #GtkSourceFile. + + + + a #GtkSourceMountOperationFactory to call when a + #GMountOperation is needed. + + + + the data to pass to the @callback function. + + + + function to call on @user_data when the @callback is no + longer needed, or %NULL. + + + + + + The compression type. + + + + The character encoding, initially %NULL. After a successful file +loading or saving operation, the encoding is non-%NULL. + + + + The location. + + + + The line ending type. + + + + Whether the file is read-only or not. The value of this property is +not updated automatically (there is no file monitors). + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #GtkSourceFileLoader object. The contents is read from the +#GtkSourceFile's location. If not already done, call +gtk_source_file_set_location() before calling this constructor. The previous +location is anyway not needed, because as soon as the file loading begins, +the @buffer is emptied. + + + a new #GtkSourceFileLoader object. + + + + + the #GtkSourceBuffer to load the contents into. + + + + the #GtkSourceFile. + + + + + + Creates a new #GtkSourceFileLoader object. The contents is read from @stream. + + + a new #GtkSourceFileLoader object. + + + + + the #GtkSourceBuffer to load the contents into. + + + + the #GtkSourceFile. + + + + the #GInputStream to load, e.g. stdin. + + + + + + + + the #GtkSourceBuffer to load the contents into. + + + + + a #GtkSourceFileLoader. + + + + + + + + the detected compression type. + + + + + a #GtkSourceFileLoader. + + + + + + + + the detected file encoding. + + + + + a #GtkSourceFileLoader. + + + + + + + + the #GtkSourceFile. + + + + + a #GtkSourceFileLoader. + + + + + + + + the #GInputStream to load, or %NULL +if a #GFile is used. + + + + + a #GtkSourceFileLoader. + + + + + + + + the #GFile to load, or %NULL +if an input stream is used. + + + + + a #GtkSourceFileLoader. + + + + + + + + the detected newline type. + + + + + a #GtkSourceFileLoader. + + + + + + Loads asynchronously the file or input stream contents into the +#GtkSourceBuffer. See the #GAsyncResult documentation to know how to use this +function. + + + + + + + a #GtkSourceFileLoader. + + + + the I/O priority of the request. E.g. %G_PRIORITY_LOW, + %G_PRIORITY_DEFAULT or %G_PRIORITY_HIGH. + + + + optional #GCancellable object, %NULL to ignore. + + + + function to call back with + progress information, or %NULL if progress information is not needed. + + + + user data to pass to @progress_callback. + + + + function to call on + @progress_callback_data when the @progress_callback is no longer needed, or + %NULL. + + + + a #GAsyncReadyCallback to call when the request is + satisfied. + + + + user data to pass to @callback. + + + + + + Finishes a file loading started with gtk_source_file_loader_load_async(). + +If the contents has been loaded, the following #GtkSourceFile properties will +be updated: the location, the encoding, the newline type and the compression +type. + + + whether the contents has been loaded successfully. + + + + + a #GtkSourceFileLoader. + + + + a #GAsyncResult. + + + + + + Sets the candidate encodings for the file loading. The encodings are tried in +the same order as the list. + +For convenience, @candidate_encodings can contain duplicates. Only the first +occurrence of a duplicated encoding is kept in the list. + +By default the candidate encodings are (in that order in the list): +1. If set, the #GtkSourceFile's encoding as returned by +gtk_source_file_get_encoding(). +2. The default candidates as returned by +gtk_source_encoding_get_default_candidates(). + + + + + + + a #GtkSourceFileLoader. + + + + a list of + #GtkSourceEncoding<!-- -->s. + + + + + + + + The #GtkSourceBuffer to load the contents into. The +#GtkSourceFileLoader object has a weak reference to the buffer. + + + + The #GtkSourceFile. The #GtkSourceFileLoader object has a weak +reference to the file. + + + + The #GInputStream to load. Useful for reading stdin. If this property +is set, the #GtkSourceFileLoader:location property is ignored. + + + + The #GFile to load. If the #GtkSourceFileLoader:input-stream is +%NULL, by default the location is taken from the #GtkSourceFile at +construction time. + + + + + + + + + + + + + + + + + + + + + + An error code used with the %GTK_SOURCE_FILE_LOADER_ERROR domain. + + The file is too big. + + + It is not +possible to detect the encoding automatically. + + + There was an encoding +conversion error and it was needed to use a fallback character. + + + + + + + + + + + + + + + + + Creates a new #GtkSourceFileSaver object. The @buffer will be saved to the +#GtkSourceFile's location. + +This constructor is suitable for a simple "save" operation, when the @file +already contains a non-%NULL #GtkSourceFile:location. + + + a new #GtkSourceFileSaver object. + + + + + the #GtkSourceBuffer to save. + + + + the #GtkSourceFile. + + + + + + Creates a new #GtkSourceFileSaver object with a target location. When the +file saving is finished successfully, @target_location is set to the @file's +#GtkSourceFile:location property. If an error occurs, the previous valid +location is still available in #GtkSourceFile. + +This constructor is suitable for a "save as" operation, or for saving a new +buffer for the first time. + + + a new #GtkSourceFileSaver object. + + + + + the #GtkSourceBuffer to save. + + + + the #GtkSourceFile. + + + + the #GFile where to save the buffer to. + + + + + + + + the #GtkSourceBuffer to save. + + + + + a #GtkSourceFileSaver. + + + + + + + + the compression type. + + + + + a #GtkSourceFileSaver. + + + + + + + + the encoding. + + + + + a #GtkSourceFileSaver. + + + + + + + + the #GtkSourceFile. + + + + + a #GtkSourceFileSaver. + + + + + + + + the flags. + + + + + a #GtkSourceFileSaver. + + + + + + + + the #GFile where to save the buffer to. + + + + + a #GtkSourceFileSaver. + + + + + + + + the newline type. + + + + + a #GtkSourceFileSaver. + + + + + + Saves asynchronously the buffer into the file. See the #GAsyncResult +documentation to know how to use this function. + + + + + + + a #GtkSourceFileSaver. + + + + the I/O priority of the request. E.g. %G_PRIORITY_LOW, + %G_PRIORITY_DEFAULT or %G_PRIORITY_HIGH. + + + + optional #GCancellable object, %NULL to ignore. + + + + function to call back with + progress information, or %NULL if progress information is not needed. + + + + user data to pass to @progress_callback. + + + + function to call on + @progress_callback_data when the @progress_callback is no longer needed, or + %NULL. + + + + a #GAsyncReadyCallback to call when the request is + satisfied. + + + + user data to pass to @callback. + + + + + + Finishes a file saving started with gtk_source_file_saver_save_async(). + +If the file has been saved successfully, the following #GtkSourceFile +properties will be updated: the location, the encoding, the newline type and +the compression type. + +Since the 3.20 version, gtk_text_buffer_set_modified() is called with %FALSE +if the file has been saved successfully. + + + whether the file was saved successfully. + + + + + a #GtkSourceFileSaver. + + + + a #GAsyncResult. + + + + + + Sets the compression type. By default the compression type is taken from the +#GtkSourceFile. + + + + + + + a #GtkSourceFileSaver. + + + + the new compression type. + + + + + + Sets the encoding. If @encoding is %NULL, the UTF-8 encoding will be set. +By default the encoding is taken from the #GtkSourceFile. + + + + + + + a #GtkSourceFileSaver. + + + + the new encoding, or %NULL for UTF-8. + + + + + + + + + + + + a #GtkSourceFileSaver. + + + + the new flags. + + + + + + Sets the newline type. By default the newline type is taken from the +#GtkSourceFile. + + + + + + + a #GtkSourceFileSaver. + + + + the new newline type. + + + + + + The #GtkSourceBuffer to save. The #GtkSourceFileSaver object has a +weak reference to the buffer. + + + + The compression type. + + + + The file's encoding. + + + + The #GtkSourceFile. The #GtkSourceFileSaver object has a weak +reference to the file. + + + + File saving flags. + + + + The #GFile where to save the buffer. By default the location is taken +from the #GtkSourceFile at construction time. + + + + The newline type. + + + + + + + + + + + + + + + + + + + + + + An error code used with the %GTK_SOURCE_FILE_SAVER_ERROR domain. + + The buffer contains invalid + characters. + + + The file is externally + modified. + + + + + + + + + Flags to define the behavior of a #GtkSourceFileSaver. + + No flags. + + + Ignore invalid characters. + + + Save file despite external modifications. + + + Create a backup before saving the file. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use gtk_source_gutter_renderer_get_padding() instead. + + + + + + + + + + + + + + + + + + Finds the #GtkSourceGutterRenderer at (x, y). + + + the renderer at (x, y) or %NULL. + + + + + A #GtkSourceGutter. + + + + The x position to get identified. + + + + The y position to get identified. + + + + + + + + the associated #GtkSourceView. + + + + + a #GtkSourceGutter. + + + + + + Get the #GdkWindow of the gutter. The window will only be available when the +gutter has at least one, non-zero width, cell renderer packed. + Use gtk_text_view_get_window() instead. + + + the #GdkWindow of the gutter, or %NULL +if the gutter has no window. + + + + + a #GtkSourceGutter. + + + + + + + + the #GtkTextWindowType of @gutter. + + + + + a #GtkSourceGutter. + + + + + + Insert @renderer into the gutter. If @renderer is yet unowned then gutter +claims its ownership. Otherwise just increases renderer's reference count. +@renderer cannot be already inserted to another gutter. + + + %TRUE if operation succeeded. Otherwise %FALSE. + + + + + a #GtkSourceGutter. + + + + a gutter renderer (must inherit from #GtkSourceGutterRenderer). + + + + the renderer position. + + + + + + Invalidates the drawable area of the gutter. You can use this to force a +redraw of the gutter if something has changed and needs to be redrawn. + + + + + + + a #GtkSourceGutter. + + + + + + Removes @renderer from @gutter. + + + + + + + a #GtkSourceGutter. + + + + a #GtkSourceGutterRenderer. + + + + + + Reorders @renderer in @gutter to new @position. + + + + + + + a #GtkSourceGutterRenderer. + + + + a #GtkCellRenderer. + + + + the new renderer position. + + + + + + Use gtk_source_gutter_renderer_set_padding() instead. + + + + + + + + + + + + + + + + + + The #GtkSourceView of the gutter. + + + + The text window type on which the window is placed. + + + + The x-padding. + Use the #GtkSourceGutterRenderer's +#GtkSourceGutterRenderer:xpad property instead. + + + + The y-padding. + Use the #GtkSourceGutterRenderer's +#GtkSourceGutterRenderer:ypad property instead. + + + + + + + + + + + + + + + + + + + + + + Emits the #GtkSourceGutterRenderer::activate signal of the renderer. This is +called from #GtkSourceGutter and should never have to be called manually. + + + + + + + a #GtkSourceGutterRenderer + + + + a #GtkTextIter at the start of the line where the renderer is activated + + + + a #GdkRectangle of the cell area where the renderer is activated + + + + the event that triggered the activation + + + + + + Called when drawing a region begins. The region to be drawn is indicated +by @start and @end. The purpose is to allow the implementation to precompute +some state before the draw method is called for each cell. + + + + + + + a #GtkSourceGutterRenderer + + + + a #cairo_t + + + + a #GdkRectangle + + + + a #GdkRectangle + + + + a #GtkTextIter + + + + a #GtkTextIter + + + + + + This is called when the text buffer changes for @renderer. + + + + + + + a #GtkSourceGutterRenderer. + + + + the old #GtkTextBuffer. + + + + + + This is called when the text view changes for @renderer. + + + + + + + a #GtkSourceGutterRenderer. + + + + the old #GtkTextView. + + + + + + Main renderering method. Implementations should implement this method to draw +onto the cairo context. The @background_area indicates the total area of the +cell to be drawn. The @cell_area indicates the area where content can be +drawn (text, images, etc). + +The @background_area is the @cell_area plus the padding on each side (two +times the #GtkSourceGutterRenderer:xpad horizontally and two times the +#GtkSourceGutterRenderer:ypad vertically, so that the @cell_area is centered +inside @background_area). + +The @state argument indicates the current state of the renderer and should +be taken into account to properly draw the different possible states +(cursor, prelit, selected) if appropriate. + + + + + + + a #GtkSourceGutterRenderer + + + + the cairo render context + + + + a #GdkRectangle indicating the total area to be drawn + + + + a #GdkRectangle indicating the area to draw content + + + + a #GtkTextIter + + + + a #GtkTextIter + + + + a #GtkSourceGutterRendererState + + + + + + Called when drawing a region of lines has ended. + + + + + + + a #GtkSourceGutterRenderer + + + + + + Get whether the renderer is activatable at the location in @event. This is +called from #GtkSourceGutter to determine whether a renderer is activatable +using the mouse pointer. + + + %TRUE if the renderer can be activated, %FALSE otherwise + + + + + a #GtkSourceGutterRenderer + + + + a #GtkTextIter at the start of the line to be activated + + + + a #GdkRectangle of the cell area to be activated + + + + the event that triggered the query + + + + + + Emit the #GtkSourceGutterRenderer::query-data signal. This function is called +to query for data just before rendering a cell. This is called from the +#GtkSourceGutter. Implementations can override the default signal handler or +can connect a signal handler externally to the +#GtkSourceGutterRenderer::query-data signal. + + + + + + + a #GtkSourceGutterRenderer. + + + + a #GtkTextIter. + + + + a #GtkTextIter. + + + + a #GtkSourceGutterRendererState. + + + + + + Emits the #GtkSourceGutterRenderer::query-tooltip signal. This function is +called from #GtkSourceGutter. Implementations can override the default signal +handler or can connect to the signal externally. + + + %TRUE if the tooltip has been set, %FALSE otherwise + + + + + a #GtkSourceGutterRenderer. + + + + a #GtkTextIter. + + + + a #GdkRectangle. + + + + The x position of the tooltip. + + + + The y position of the tooltip. + + + + a #GtkTooltip. + + + + + + Emits the #GtkSourceGutterRenderer::queue-draw signal of the renderer. Call +this from an implementation to inform that the renderer has changed such that +it needs to redraw. + + + + + + + a #GtkSourceGutterRenderer + + + + + + Emits the #GtkSourceGutterRenderer::activate signal of the renderer. This is +called from #GtkSourceGutter and should never have to be called manually. + + + + + + + a #GtkSourceGutterRenderer + + + + a #GtkTextIter at the start of the line where the renderer is activated + + + + a #GdkRectangle of the cell area where the renderer is activated + + + + the event that triggered the activation + + + + + + Called when drawing a region begins. The region to be drawn is indicated +by @start and @end. The purpose is to allow the implementation to precompute +some state before the draw method is called for each cell. + + + + + + + a #GtkSourceGutterRenderer + + + + a #cairo_t + + + + a #GdkRectangle + + + + a #GdkRectangle + + + + a #GtkTextIter + + + + a #GtkTextIter + + + + + + Main renderering method. Implementations should implement this method to draw +onto the cairo context. The @background_area indicates the total area of the +cell to be drawn. The @cell_area indicates the area where content can be +drawn (text, images, etc). + +The @background_area is the @cell_area plus the padding on each side (two +times the #GtkSourceGutterRenderer:xpad horizontally and two times the +#GtkSourceGutterRenderer:ypad vertically, so that the @cell_area is centered +inside @background_area). + +The @state argument indicates the current state of the renderer and should +be taken into account to properly draw the different possible states +(cursor, prelit, selected) if appropriate. + + + + + + + a #GtkSourceGutterRenderer + + + + the cairo render context + + + + a #GdkRectangle indicating the total area to be drawn + + + + a #GdkRectangle indicating the area to draw content + + + + a #GtkTextIter + + + + a #GtkTextIter + + + + a #GtkSourceGutterRendererState + + + + + + Called when drawing a region of lines has ended. + + + + + + + a #GtkSourceGutterRenderer + + + + + + Get the x-alignment and y-alignment of the gutter renderer. + + + + + + + a #GtkSourceGutterRenderer + + + + return location for the x-alignment, + or %NULL to ignore. + + + + return location for the y-alignment, + or %NULL to ignore. + + + + + + Get the alignment mode. The alignment mode describes the manner in which the +renderer is aligned (see :xalign and :yalign). + + + a #GtkSourceGutterRendererAlignmentMode + + + + + a #GtkSourceGutterRenderer + + + + + + Get the background color of the renderer. + + + %TRUE if the background color is set, %FALSE otherwise + + + + + a #GtkSourceGutterRenderer + + + + return value for a #GdkRGBA + + + + + + Get the x-padding and y-padding of the gutter renderer. + + + + + + + a #GtkSourceGutterRenderer + + + + return location for the x-padding, + or %NULL to ignore. + + + + return location for the y-padding, + or %NULL to ignore. + + + + + + Get the size of the renderer. + + + the size of the renderer. + + + + + a #GtkSourceGutterRenderer + + + + + + Get the view associated to the gutter renderer + + + a #GtkTextView + + + + + a #GtkSourceGutterRenderer + + + + + + Get whether the gutter renderer is visible. + + + %TRUE if the renderer is visible, %FALSE otherwise + + + + + a #GtkSourceGutterRenderer + + + + + + Get the #GtkTextWindowType associated with the gutter renderer. + + + a #GtkTextWindowType + + + + + a #GtkSourceGutterRenderer + + + + + + Get whether the renderer is activatable at the location in @event. This is +called from #GtkSourceGutter to determine whether a renderer is activatable +using the mouse pointer. + + + %TRUE if the renderer can be activated, %FALSE otherwise + + + + + a #GtkSourceGutterRenderer + + + + a #GtkTextIter at the start of the line to be activated + + + + a #GdkRectangle of the cell area to be activated + + + + the event that triggered the query + + + + + + Emit the #GtkSourceGutterRenderer::query-data signal. This function is called +to query for data just before rendering a cell. This is called from the +#GtkSourceGutter. Implementations can override the default signal handler or +can connect a signal handler externally to the +#GtkSourceGutterRenderer::query-data signal. + + + + + + + a #GtkSourceGutterRenderer. + + + + a #GtkTextIter. + + + + a #GtkTextIter. + + + + a #GtkSourceGutterRendererState. + + + + + + Emits the #GtkSourceGutterRenderer::query-tooltip signal. This function is +called from #GtkSourceGutter. Implementations can override the default signal +handler or can connect to the signal externally. + + + %TRUE if the tooltip has been set, %FALSE otherwise + + + + + a #GtkSourceGutterRenderer. + + + + a #GtkTextIter. + + + + a #GdkRectangle. + + + + The x position of the tooltip. + + + + The y position of the tooltip. + + + + a #GtkTooltip. + + + + + + Emits the #GtkSourceGutterRenderer::queue-draw signal of the renderer. Call +this from an implementation to inform that the renderer has changed such that +it needs to redraw. + + + + + + + a #GtkSourceGutterRenderer + + + + + + Set the alignment of the gutter renderer. Both @xalign and @yalign can be +-1, which means the values will not be changed (this allows changing only +one of the values). + +@xalign is the horizontal alignment. Set to 0 for a left alignment. 1 for a +right alignment. And 0.5 for centering the cells. @yalign is the vertical +alignment. Set to 0 for a top alignment. 1 for a bottom alignment. + + + + + + + a #GtkSourceGutterRenderer + + + + the x-alignment + + + + the y-alignment + + + + + + Set the alignment mode. The alignment mode describes the manner in which the +renderer is aligned (see :xalign and :yalign). + + + + + + + a #GtkSourceGutterRenderer + + + + a #GtkSourceGutterRendererAlignmentMode + + + + + + Set the background color of the renderer. If @color is set to %NULL, the +renderer will not have a background color. + + + + + + + a #GtkSourceGutterRenderer + + + + a #GdkRGBA or %NULL + + + + + + Set the padding of the gutter renderer. Both @xpad and @ypad can be +-1, which means the values will not be changed (this allows changing only +one of the values). + +@xpad is the left and right padding. @ypad is the top and bottom padding. + + + + + + + a #GtkSourceGutterRenderer + + + + the x-padding + + + + the y-padding + + + + + + Sets the size of the renderer. A value of -1 specifies that the size +is to be determined dynamically. + + + + + + + a #GtkSourceGutterRenderer + + + + the size + + + + + + Set whether the gutter renderer is visible. + + + + + + + a #GtkSourceGutterRenderer + + + + the visibility + + + + + + The alignment mode of the renderer. This can be used to indicate +that in the case a cell spans multiple lines (due to text wrapping) +the alignment should work on either the full cell, the first line +or the last line. + + + + + + + + + + + + + The view on which the renderer is placed. + + + + The visibility of the renderer. + + + + The window type of the view on which the renderer is placed (left, +or right). + + + + The horizontal alignment of the renderer. Set to 0 for a left +alignment. 1 for a right alignment. And 0.5 for centering the cells. +A value lower than 0 doesn't modify the alignment. + + + + The left and right padding of the renderer. + + + + The vertical alignment of the renderer. Set to 0 for a top +alignment. 1 for a bottom alignment. And 0.5 for centering the cells. +A value lower than 0 doesn't modify the alignment. + + + + The top and bottom padding of the renderer. + + + + + + + + + + The ::activate signal is emitted when the renderer is +activated. + + + + + + a #GtkTextIter + + + + a #GdkRectangle + + + + the event that caused the activation + + + + + + The ::query-activatable signal is emitted when the renderer +can possibly be activated. + + + + + + a #GtkTextIter + + + + a #GdkRectangle + + + + the #GdkEvent that is causing the activatable query + + + + + + The ::query-data signal is emitted when the renderer needs +to be filled with data just before a cell is drawn. This can +be used by general renderer implementations to allow render +data to be filled in externally. + + + + + + a #GtkTextIter + + + + a #GtkTextIter + + + + the renderer state + + + + + + The ::query-tooltip signal is emitted when the renderer can +show a tooltip. + + + + + + a #GtkTextIter + + + + a #GdkRectangle + + + + the x position (in window coordinates) + + + + the y position (in window coordinates) + + + + a #GtkTooltip + + + + + + The ::queue-draw signal is emitted when the renderer needs +to be redrawn. Use gtk_source_gutter_renderer_queue_draw() +to emit this signal from an implementation of the +#GtkSourceGutterRenderer interface. + + + + + + + The alignment mode of the renderer, when a cell spans multiple lines (due to +text wrapping). + + The full cell. + + + The first line. + + + The last line. + + + + + + + + + + + + + + + + a #GtkSourceGutterRenderer + + + + a #cairo_t + + + + a #GdkRectangle + + + + a #GdkRectangle + + + + a #GtkTextIter + + + + a #GtkTextIter + + + + + + + + + + + + + + a #GtkSourceGutterRenderer + + + + the cairo render context + + + + a #GdkRectangle indicating the total area to be drawn + + + + a #GdkRectangle indicating the area to draw content + + + + a #GtkTextIter + + + + a #GtkTextIter + + + + a #GtkSourceGutterRendererState + + + + + + + + + + + + + + a #GtkSourceGutterRenderer + + + + + + + + + + + + + + a #GtkSourceGutterRenderer. + + + + the old #GtkTextView. + + + + + + + + + + + + + + a #GtkSourceGutterRenderer. + + + + the old #GtkTextBuffer. + + + + + + + + + + %TRUE if the renderer can be activated, %FALSE otherwise + + + + + a #GtkSourceGutterRenderer + + + + a #GtkTextIter at the start of the line to be activated + + + + a #GdkRectangle of the cell area to be activated + + + + the event that triggered the query + + + + + + + + + + + + + + a #GtkSourceGutterRenderer + + + + a #GtkTextIter at the start of the line where the renderer is activated + + + + a #GdkRectangle of the cell area where the renderer is activated + + + + the event that triggered the activation + + + + + + + + + + + + + + a #GtkSourceGutterRenderer + + + + + + + + + + %TRUE if the tooltip has been set, %FALSE otherwise + + + + + a #GtkSourceGutterRenderer. + + + + a #GtkTextIter. + + + + a #GdkRectangle. + + + + The x position of the tooltip. + + + + The y position of the tooltip. + + + + a #GtkTooltip. + + + + + + + + + + + + + + a #GtkSourceGutterRenderer. + + + + a #GtkTextIter. + + + + a #GtkTextIter. + + + + a #GtkSourceGutterRendererState. + + + + + + + + + + Create a new #GtkSourceGutterRendererPixbuf. + + + A #GtkSourceGutterRenderer + + + + + Get the gicon of the renderer + + + a #GIcon + + + + + a #GtkSourceGutterRendererPixbuf + + + + + + + + + + + + + + + + + Get the pixbuf of the renderer. + + + a #GdkPixbuf + + + + + a #GtkSourceGutterRendererPixbuf + + + + + + Don't use this function. + + + the stock id. + + + + + a #GtkSourceGutterRendererPixbuf + + + + + + + + + + + + a #GtkSourceGutterRendererPixbuf + + + + the icon, or %NULL. + + + + + + + + + + + + a #GtkSourceGutterRendererPixbuf + + + + the icon name, or %NULL. + + + + + + + + + + + + a #GtkSourceGutterRendererPixbuf + + + + the pixbuf, or %NULL. + + + + + + Don't use this function. + + + + + + + a #GtkSourceGutterRendererPixbuf + + + + the stock id + + + + + + + + + + + + + + + The stock id. + Don't use this property. + + + + + + + + + + + + + + + + + + + + + + + + normal state + + + area in the renderer represents the +line on which the insert cursor is currently positioned + + + the mouse pointer is currently +over the activatable area of the renderer + + + area in the renderer represents +a line in the buffer which contains part of the selection + + + + + + Create a new #GtkSourceGutterRendererText. + + + A #GtkSourceGutterRenderer + + + + + Measures the text provided using the pango layout used by the +#GtkSourceGutterRendererText. + + + + + + + a #GtkSourceGutterRendererText. + + + + the text to measure. + + + + location to store the width of the text in pixels, + or %NULL. + + + + location to store the height of the text in + pixels, or %NULL. + + + + + + Measures the pango markup provided using the pango layout used by the +#GtkSourceGutterRendererText. + + + + + + + a #GtkSourceGutterRendererText. + + + + the pango markup to measure. + + + + location to store the width of the text in pixels, + or %NULL. + + + + location to store the height of the text in + pixels, or %NULL. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the globs associated to this language. This is just +an utility wrapper around gtk_source_language_get_metadata() to +retrieve the "globs" metadata property and split it into an array. + + + +a newly-allocated %NULL terminated array containing the globs or %NULL +if no globs are found. +The returned array must be freed with g_strfreev(). + + + + + + + a #GtkSourceLanguage. + + + + + + Returns whether the language should be hidden from the user. + + + %TRUE if the language should be hidden, %FALSE otherwise. + + + + + a #GtkSourceLanguage + + + + + + Returns the ID of the language. The ID is not locale-dependent. +The returned string is owned by @language and should not be freed +or modified. + + + the ID of @language. + + + + + a #GtkSourceLanguage. + + + + + + + + value of property @name stored in +the metadata of @language or %NULL if language does not contain the +specified metadata property. +The returned string is owned by @language and should not be freed +or modified. + + + + + a #GtkSourceLanguage. + + + + metadata property name. + + + + + + Returns the mime types associated to this language. This is just +an utility wrapper around gtk_source_language_get_metadata() to +retrieve the "mimetypes" metadata property and split it into an +array. + + + +a newly-allocated %NULL terminated array containing the mime types +or %NULL if no mime types are found. +The returned array must be freed with g_strfreev(). + + + + + + + a #GtkSourceLanguage. + + + + + + Returns the localized name of the language. +The returned string is owned by @language and should not be freed +or modified. + + + the name of @language. + + + + + a #GtkSourceLanguage. + + + + + + Returns the localized section of the language. +Each language belong to a section (ex. HTML belogs to the +Markup section). +The returned string is owned by @language and should not be freed +or modified. + + + the section of @language. + + + + + a #GtkSourceLanguage. + + + + + + Returns the ID of the style to use if the specified @style_id +is not present in the current style scheme. + + + the ID of the style to use if the +specified @style_id is not present in the current style scheme or %NULL +if the style has no fallback defined. +The returned string is owned by the @language and must not be modified. + + + + + a #GtkSourceLanguage. + + + + a style ID. + + + + + + Returns the ids of the styles defined by this @language. + + + +a newly-allocated %NULL terminated array containing ids of the +styles defined by this @language or %NULL if no style is defined. +The returned array must be freed with g_strfreev(). + + + + + + + a #GtkSourceLanguage. + + + + + + Returns the name of the style with ID @style_id defined by this @language. + + + the name of the style with ID @style_id +defined by this @language or %NULL if the style has no name or there is no +style with ID @style_id defined by this @language. +The returned string is owned by the @language and must not be modified. + + + + + a #GtkSourceLanguage. + + + + a style ID. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new language manager. If you do not need more than one language +manager or a private language manager instance then use +gtk_source_language_manager_get_default() instead. + + + a new #GtkSourceLanguageManager. + + + + + Returns the default #GtkSourceLanguageManager instance. + + + a #GtkSourceLanguageManager. +Return value is owned by GtkSourceView library and must not be unref'ed. + + + + + Gets the #GtkSourceLanguage identified by the given @id in the language +manager. + + + a #GtkSourceLanguage, or %NULL +if there is no language identified by the given @id. Return value is +owned by @lm and should not be freed. + + + + + a #GtkSourceLanguageManager. + + + + a language id. + + + + + + Returns the ids of the available languages. + + + +a %NULL-terminated array of strings containing the ids of the available +languages or %NULL if no language is available. +The array is sorted alphabetically according to the language name. +The array is owned by @lm and must not be modified. + + + + + + + a #GtkSourceLanguageManager. + + + + + + Gets the list directories where @lm looks for language files. + + + %NULL-terminated array +containg a list of language files directories. +The array is owned by @lm and must not be modified. + + + + + + + a #GtkSourceLanguageManager. + + + + + + Picks a #GtkSourceLanguage for given file name and content type, +according to the information in lang files. Either @filename or +@content_type may be %NULL. This function can be used as follows: + +<informalexample><programlisting> + GtkSourceLanguage *lang; + lang = gtk_source_language_manager_guess_language (filename, NULL); + gtk_source_buffer_set_language (buffer, lang); +</programlisting></informalexample> + +or + +<informalexample><programlisting> + GtkSourceLanguage *lang = NULL; + gboolean result_uncertain; + gchar *content_type; + + content_type = g_content_type_guess (filename, NULL, 0, &result_uncertain); + if (result_uncertain) + { + g_free (content_type); + content_type = NULL; + } + + lang = gtk_source_language_manager_guess_language (manager, filename, content_type); + gtk_source_buffer_set_language (buffer, lang); + + g_free (content_type); +</programlisting></informalexample> + +etc. Use gtk_source_language_get_mime_types() and gtk_source_language_get_globs() +if you need full control over file -> language mapping. + + + a #GtkSourceLanguage, or %NULL if there +is no suitable language for given @filename and/or @content_type. Return +value is owned by @lm and should not be freed. + + + + + a #GtkSourceLanguageManager. + + + + a filename in Glib filename encoding, or %NULL. + + + + a content type (as in GIO API), or %NULL. + + + + + + Sets the list of directories where the @lm looks for +language files. +If @dirs is %NULL, the search path is reset to default. + +<note> + <para> + At the moment this function can be called only before the + language files are loaded for the first time. In practice + to set a custom search path for a #GtkSourceLanguageManager, + you have to call this function right after creating it. + </para> +</note> + + + + + + + a #GtkSourceLanguageManager. + + + + +a %NULL-terminated array of strings or %NULL. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #GtkSourceMap. + + + a new #GtkSourceMap. + + + + + Gets the #GtkSourceMap:view property, which is the view this widget is mapping. + + + a #GtkSourceView or %NULL. + + + + + a #GtkSourceMap. + + + + + + Sets the view that @map will be doing the mapping to. + + + + + + + a #GtkSourceMap + + + + a #GtkSourceView + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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(). +Normally marks are created using the utility function +gtk_source_buffer_create_source_mark(). + + + a new #GtkSourceMark that can be added using gtk_text_buffer_add_mark(). + + + + + Name of the #GtkSourceMark, can be NULL when not using a name + + + + is used to classify marks according to common characteristics +(e.g. all the marks representing a bookmark could belong to the "bookmark" +category, or all the marks representing a compilation error could belong to +"error" category). + + + + + + Returns the mark category. + + + the category of the #GtkSourceMark. + + + + + a #GtkSourceMark. + + + + + + Returns the next #GtkSourceMark in the buffer or %NULL if the mark +was not added to a buffer. If there is no next mark, %NULL will be returned. + +If @category is %NULL, looks for marks of any category. + + + the next #GtkSourceMark, or %NULL. + + + + + a #GtkSourceMark. + + + + a string specifying the mark category, or %NULL. + + + + + + Returns the previous #GtkSourceMark in the buffer or %NULL if the mark +was not added to a buffer. If there is no previous mark, %NULL is returned. + +If @category is %NULL, looks for marks of any category + + + the previous #GtkSourceMark, or %NULL. + + + + + a #GtkSourceMark. + + + + a string specifying the mark category, or %NULL. + + + + + + The category of the #GtkSourceMark, classifies the mark and controls +which pixbuf is used and with which priority it is drawn. + + + + + + + + + + + + + Creates a new source mark attributes. + + + a new source mark attributes. + + + + + Stores background color in @background. + + + whether background color for @attributes was set. + + + + + a #GtkSourceMarkAttributes. + + + + a #GdkRGBA. + + + + + + Gets a #GIcon to be used as a base for rendered icon. Note that the icon can +be %NULL if it wasn't set earlier. + + + An icon. The icon belongs to @attributes and should +not be unreffed. + + + + + a #GtkSourceMarkAttributes. + + + + + + Gets a name of an icon to be used as a base for rendered icon. Note that the +icon name can be %NULL if it wasn't set earlier. + + + An icon name. The string belongs to @attributes and +should not be freed. + + + + + a #GtkSourceMarkAttributes. + + + + + + Gets a #GdkPixbuf to be used as a base for rendered icon. Note that the +pixbuf can be %NULL if it wasn't set earlier. + + + A pixbuf. The pixbuf belongs to @attributes and +should not be unreffed. + + + + + a #GtkSourceMarkAttributes. + + + + + + Gets a stock id of an icon used by this attributes. Note that the stock id can +be %NULL if it wasn't set earlier. + Don't use this function. + + + Stock id. Returned string is owned by @attributes and +shouldn't be freed. + + + + + a #GtkSourceMarkAttributes. + + + + + + Queries for a tooltip by emitting +a #GtkSourceMarkAttributes::query-tooltip-markup signal. The tooltip may contain +a markup. + + + A tooltip. The returned string should be freed by +using g_free() when done with it. + + + + + a #GtkSourceMarkAttributes. + + + + a #GtkSourceMark. + + + + + + Queries for a tooltip by emitting +a #GtkSourceMarkAttributes::query-tooltip-text signal. The tooltip is a plain +text. + + + A tooltip. The returned string should be freed by +using g_free() when done with it. + + + + + a #GtkSourceMarkAttributes. + + + + a #GtkSourceMark. + + + + + + Renders an icon of given size. The base of the icon is set by the last call +to one of: gtk_source_mark_attributes_set_pixbuf(), +gtk_source_mark_attributes_set_gicon(), +gtk_source_mark_attributes_set_icon_name() or +gtk_source_mark_attributes_set_stock_id(). @size cannot be lower than 1. + + + A rendered pixbuf. The pixbuf belongs to @attributes +and should not be unreffed. + + + + + a #GtkSourceMarkAttributes. + + + + widget of which style settings may be used. + + + + size of the rendered icon. + + + + + + Sets background color to the one given in @background. + + + + + + + a #GtkSourceMarkAttributes. + + + + a #GdkRGBA. + + + + + + Sets an icon to be used as a base for rendered icon. + + + + + + + a #GtkSourceMarkAttributes. + + + + a #GIcon to be used. + + + + + + Sets a name of an icon to be used as a base for rendered icon. + + + + + + + a #GtkSourceMarkAttributes. + + + + name of an icon to be used. + + + + + + Sets a pixbuf to be used as a base for rendered icon. + + + + + + + a #GtkSourceMarkAttributes. + + + + a #GdkPixbuf to be used. + + + + + + Sets stock id to be used as a base for rendered icon. + Don't use this function. + + + + + + + a #GtkSourceMarkAttributes. + + + + a stock id. + + + + + + A color used for background of a line. + + + + A #GIcon that may be a base of a rendered icon. + + + + An icon name that may be a base of a rendered icon. + + + + A #GdkPixbuf that may be a base of a rendered icon. + + + + A stock id that may be a base of a rendered icon. + Don't use this property. + + + + + + + + + + The code should connect to this signal to provide a tooltip for given +@mark. The tooltip can contain a markup. + + A tooltip. The string should be freed with +g_free() when done with it. + + + + + The #GtkSourceMark. + + + + + + The code should connect to this signal to provide a tooltip for given +@mark. The tooltip should be just a plain text. + + A tooltip. The string should be freed with +g_free() when done with it. + + + + + The #GtkSourceMark. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Type definition for a function that will be called to create a +#GMountOperation. This is useful for creating a #GtkMountOperation. + + + + + + + a #GtkSourceFile. + + + + user data + + + + + + + line feed, used on UNIX. + + + carriage return, used on Mac. + + + carriage return followed by a line feed, used + on Windows. + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new print compositor that can be used to print @buffer. + + + a new print compositor object. + + + + + the #GtkSourceBuffer to print. + + + + + + Creates a new print compositor that can be used to print the buffer +associated with @view. +This constructor sets some configuration properties to make the +printed output match @view as much as possible. The properties set are +#GtkSourcePrintCompositor:tab-width, #GtkSourcePrintCompositor:highlight-syntax, +#GtkSourcePrintCompositor:wrap-mode, #GtkSourcePrintCompositor:body-font-name and +#GtkSourcePrintCompositor:print-line-numbers. + + + a new print compositor object. + + + + + a #GtkSourceView to get configuration from. + + + + + + Draw page @page_nr for printing on the the Cairo context encapsuled in @context. + +This method has been designed to be called in the handler of the #GtkPrintOperation::draw_page signal +as shown in the following example: + +<informalexample><programlisting> +// Signal handler for the GtkPrintOperation::draw_page signal + +static void +draw_page (GtkPrintOperation *operation, + GtkPrintContext *context, + gint page_nr, + gpointer user_data) +{ + GtkSourcePrintCompositor *compositor; + + compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data); + + gtk_source_print_compositor_draw_page (compositor, + context, + page_nr); +} +</programlisting></informalexample> + + + + + + + a #GtkSourcePrintCompositor. + + + + the #GtkPrintContext encapsulating the context information that is required when + drawing the page for printing. + + + + the number of the page to print. + + + + + + Returns the name of the font used to print the text body. The returned string +must be freed with g_free(). + + + a new string containing the name of the font used to print the +text body. + + + + + a #GtkSourcePrintCompositor. + + + + + + Gets the bottom margin in units of @unit. + + + the bottom margin. + + + + + a #GtkSourcePrintCompositor. + + + + the unit for the return value. + + + + + + Gets the #GtkSourceBuffer associated with the compositor. The returned +object reference is owned by the compositor object and +should not be unreferenced. + + + the #GtkSourceBuffer associated with the compositor. + + + + + a #GtkSourcePrintCompositor. + + + + + + Returns the name of the font used to print the page footer. +The returned string must be freed with g_free(). + + + a new string containing the name of the font used to print +the page footer. + + + + + a #GtkSourcePrintCompositor. + + + + + + Returns the name of the font used to print the page header. +The returned string must be freed with g_free(). + + + a new string containing the name of the font used to print +the page header. + + + + + a #GtkSourcePrintCompositor. + + + + + + Determines whether the printed text will be highlighted according to the +buffer rules. Note that highlighting will happen +only if the buffer to print has highlighting activated. + + + %TRUE if the printed output will be highlighted. + + + + + a #GtkSourcePrintCompositor. + + + + + + Gets the left margin in units of @unit. + + + the left margin + + + + + a #GtkSourcePrintCompositor. + + + + the unit for the return value. + + + + + + Returns the name of the font used to print line numbers on the left margin. +The returned string must be freed with g_free(). + + + a new string containing the name of the font used to print +line numbers on the left margin. + + + + + a #GtkSourcePrintCompositor. + + + + + + Returns the number of pages in the document or <code>-1</code> if the +document has not been completely paginated. + + + the number of pages in the document or <code>-1</code> if the +document has not been completely paginated. + + + + + a #GtkSourcePrintCompositor. + + + + + + Returns the current fraction of the document pagination that has been completed. + + + a fraction from 0.0 to 1.0 inclusive. + + + + + a #GtkSourcePrintCompositor. + + + + + + Determines if a footer is set to be printed for each page. A +footer will be printed if this function returns %TRUE +<emphasis>and</emphasis> some format strings have been specified +with gtk_source_print_compositor_set_footer_format(). + + + %TRUE if the footer is set to be printed. + + + + + a #GtkSourcePrintCompositor. + + + + + + Determines if a header is set to be printed for each page. A +header will be printed if this function returns %TRUE +<emphasis>and</emphasis> some format strings have been specified +with gtk_source_print_compositor_set_header_format(). + + + %TRUE if the header is set to be printed. + + + + + a #GtkSourcePrintCompositor. + + + + + + Returns the interval used for line number printing. If the +value is 0, no line numbers will be printed. The default value is +1 (i.e. numbers printed in all lines). + + + the interval of printed line numbers. + + + + + a #GtkSourcePrintCompositor. + + + + + + Gets the right margin in units of @unit. + + + the right margin. + + + + + a #GtkSourcePrintCompositor. + + + + the unit for the return value. + + + + + + Returns the width of tabulation in characters for printed text. + + + width of tab. + + + + + a #GtkSourcePrintCompositor. + + + + + + Gets the top margin in units of @unit. + + + the top margin. + + + + + a #GtkSourcePrintCompositor. + + + + the unit for the return value. + + + + + + Gets the line wrapping mode for the printed text. + + + the line wrap mode. + + + + + a #GtkSourcePrintCompositor. + + + + + + Paginate the document associated with the @compositor. + +In order to support non-blocking pagination, document is paginated in small chunks. +Each time gtk_source_print_compositor_paginate() is invoked, a chunk of the document +is paginated. To paginate the entire document, gtk_source_print_compositor_paginate() +must be invoked multiple times. +It returns %TRUE if the document has been completely paginated, otherwise it returns %FALSE. + +This method has been designed to be invoked in the handler of the #GtkPrintOperation::paginate signal, +as shown in the following example: + +<informalexample><programlisting> +// Signal handler for the GtkPrintOperation::paginate signal + +static gboolean +paginate (GtkPrintOperation *operation, + GtkPrintContext *context, + gpointer user_data) +{ + GtkSourcePrintCompositor *compositor; + + compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data); + + if (gtk_source_print_compositor_paginate (compositor, context)) + { + gint n_pages; + + n_pages = gtk_source_print_compositor_get_n_pages (compositor); + gtk_print_operation_set_n_pages (operation, n_pages); + + return TRUE; + } + + return FALSE; +} +</programlisting></informalexample> + +If you don't need to do pagination in chunks, you can simply do it all in the +#GtkPrintOperation::begin-print handler, and set the number of pages from there, like +in the following example: + +<informalexample><programlisting> +// Signal handler for the GtkPrintOperation::begin-print signal + +static void +begin_print (GtkPrintOperation *operation, + GtkPrintContext *context, + gpointer user_data) +{ + GtkSourcePrintCompositor *compositor; + gint n_pages; + + compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data); + + while (!gtk_source_print_compositor_paginate (compositor, context)); + + n_pages = gtk_source_print_compositor_get_n_pages (compositor); + gtk_print_operation_set_n_pages (operation, n_pages); +} +</programlisting></informalexample> + + + %TRUE if the document has been completely paginated, %FALSE otherwise. + + + + + a #GtkSourcePrintCompositor. + + + + the #GtkPrintContext whose parameters (e.g. paper size, print margins, etc.) +are used by the the @compositor to paginate the document. + + + + + + Sets the default font for the printed text. + +@font_name should be a +string representation of a font description Pango can understand. +(e.g. &quot;Monospace 10&quot;). See pango_font_description_from_string() +for a description of the format of the string representation. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + the name of the default font for the body text. + + + + + + Sets the bottom margin used by @compositor. + + + + + + + a #GtkSourcePrintCompositor. + + + + the new bottom margin in units of @unit. + + + + the units for @margin. + + + + + + Sets the font for printing the page footer. If +%NULL is supplied, the default font (i.e. the one being used for the +text) will be used instead. + +@font_name should be a +string representation of a font description Pango can understand. +(e.g. &quot;Monospace 10&quot;). See pango_font_description_from_string() +for a description of the format of the string representation. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + the name of the font for the footer text, or %NULL. + + + + + + See gtk_source_print_compositor_set_header_format() for more information +about the parameters. + + + + + + + a #GtkSourcePrintCompositor. + + + + %TRUE if you want a separator line to be printed. + + + + a format string to print on the left of the footer. + + + + a format string to print on the center of the footer. + + + + a format string to print on the right of the footer. + + + + + + Sets the font for printing the page header. If +%NULL is supplied, the default font (i.e. the one being used for the +text) will be used instead. + +@font_name should be a +string representation of a font description Pango can understand. +(e.g. &quot;Monospace 10&quot;). See pango_font_description_from_string() +for a description of the format of the string representation. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + the name of the font for header text, or %NULL. + + + + + + Sets strftime like header format strings, to be printed on the +left, center and right of the top of each page. The strings may +include strftime(3) codes which will be expanded at print time. +A subset of strftime() codes are accepted, see g_date_time_format() +for more details on the accepted format specifiers. +Additionally the following format specifiers are accepted: +- #N: the page number +- #Q: the page count. + +@separator specifies if a solid line should be drawn to separate +the header from the document text. + +If %NULL is given for any of the three arguments, that particular +string will not be printed. + +For the header to be printed, in +addition to specifying format strings, you need to enable header +printing with gtk_source_print_compositor_set_print_header(). + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + %TRUE if you want a separator line to be printed. + + + + a format string to print on the left of the header. + + + + a format string to print on the center of the header. + + + + a format string to print on the right of the header. + + + + + + Sets whether the printed text will be highlighted according to the +buffer rules. Both color and font style are applied. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + whether syntax should be highlighted. + + + + + + Sets the left margin used by @compositor. + + + + + + + a #GtkSourcePrintCompositor. + + + + the new left margin in units of @unit. + + + + the units for @margin. + + + + + + Sets the font for printing line numbers on the left margin. If +%NULL is supplied, the default font (i.e. the one being used for the +text) will be used instead. + +@font_name should be a +string representation of a font description Pango can understand. +(e.g. &quot;Monospace 10&quot;). See pango_font_description_from_string() +for a description of the format of the string representation. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + the name of the font for line numbers, or %NULL. + + + + + + Sets whether you want to print a footer in each page. The +footer consists of three pieces of text and an optional line +separator, configurable with +gtk_source_print_compositor_set_footer_format(). + +Note that by default the footer format is unspecified, and if it's +empty it will not be printed, regardless of this setting. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + %TRUE if you want the footer to be printed. + + + + + + Sets whether you want to print a header in each page. The +header consists of three pieces of text and an optional line +separator, configurable with +gtk_source_print_compositor_set_header_format(). + +Note that by default the header format is unspecified, and if it's +empty it will not be printed, regardless of this setting. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + %TRUE if you want the header to be printed. + + + + + + Sets the interval for printed line numbers. If @interval is 0 no +numbers will be printed. If greater than 0, a number will be +printed every @interval lines (i.e. 1 will print all line numbers). + +Maximum accepted value for @interval is 100. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + interval for printed line numbers. + + + + + + Sets the right margin used by @compositor. + + + + + + + a #GtkSourcePrintCompositor. + + + + the new right margin in units of @unit. + + + + the units for @margin. + + + + + + Sets the width of tabulation in characters for printed text. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + width of tab in characters. + + + + + + Sets the top margin used by @compositor. + + + + + + + a #GtkSourcePrintCompositor. + + + + the new top margin in units of @unit + + + + the units for @margin + + + + + + Sets the line wrapping mode for the printed text. + +This function cannot be called anymore after the first call to the +gtk_source_print_compositor_paginate() function. + + + + + + + a #GtkSourcePrintCompositor. + + + + a #GtkWrapMode. + + + + + + Name of the font used for the text body. + +Accepted values are strings representing a font description Pango can understand. +(e.g. &quot;Monospace 10&quot;). See pango_font_description_from_string() +for a description of the format of the string representation. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + The GtkSourceBuffer object to print. + + + + Name of the font used to print page footer. +If this property is unspecified, the text body font is used. + +Accepted values are strings representing a font description Pango can understand. +(e.g. &quot;Monospace 10&quot;). See pango_font_description_from_string() +for a description of the format of the string representation. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + Name of the font used to print page header. +If this property is unspecified, the text body font is used. + +Accepted values are strings representing a font description Pango can understand. +(e.g. &quot;Monospace 10&quot;). See pango_font_description_from_string() +for a description of the format of the string representation. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + Whether to print the document with highlighted syntax. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + Name of the font used to print line numbers on the left margin. +If this property is unspecified, the text body font is used. + +Accepted values are strings representing a font description Pango can understand. +(e.g. &quot;Monospace 10&quot;). See pango_font_description_from_string() +for a description of the format of the string representation. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + The number of pages in the document or <code>-1</code> if the +document has not been completely paginated. + + + + Whether to print a footer in each page. + +Note that by default the footer format is unspecified, and if it is +unspecified the footer will not be printed, regardless of the value of +this property. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + Whether to print a header in each page. + +Note that by default the header format is unspecified, and if it is +unspecified the header will not be printed, regardless of the value of +this property. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + Interval of printed line numbers. If this property is set to 0 no +numbers will be printed. If greater than 0, a number will be +printed every "print-line-numbers" lines (i.e. 1 will print all line numbers). + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + Width of a tab character expressed in spaces. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + Whether to wrap lines never, at word boundaries, or at character boundaries. + +The value of this property cannot be changed anymore after the first +call to the gtk_source_print_compositor_paginate() function. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a new #GtkSourceRegion object for @buffer. + + + + + a #GtkTextBuffer. + + + + + + Adds @region_to_add to @region. @region_to_add is not modified. + + + + + + + a #GtkSourceRegion. + + + + the #GtkSourceRegion to add to @region, or %NULL. + + + + + + Adds the subregion delimited by @_start and @_end to @region. + + + + + + + a #GtkSourceRegion. + + + + the start of the subregion. + + + + the end of the subregion. + + + + + + Gets the @start and @end bounds of the @region. + + + %TRUE if @start and @end have been set successfully (if non-%NULL), + or %FALSE if the @region is empty. + + + + + a #GtkSourceRegion. + + + + iterator to initialize with the start of @region, + or %NULL. + + + + iterator to initialize with the end of @region, + or %NULL. + + + + + + + + the #GtkTextBuffer. + + + + + a #GtkSourceRegion. + + + + + + Initializes a #GtkSourceRegionIter to the first subregion of @region. If +@region is empty, @iter will be initialized to the end iterator. + + + + + + + a #GtkSourceRegion. + + + + iterator to initialize to the first subregion. + + + + + + Returns the intersection between @region1 and @region2. @region1 and +@region2 are not modified. + + + the intersection as a #GtkSourceRegion + object. + + + + + a #GtkSourceRegion, or %NULL. + + + + a #GtkSourceRegion, or %NULL. + + + + + + Returns the intersection between @region and the subregion delimited by +@_start and @_end. @region is not modified. + + + the intersection as a new + #GtkSourceRegion. + + + + + a #GtkSourceRegion. + + + + the start of the subregion. + + + + the end of the subregion. + + + + + + Returns whether the @region is empty. A %NULL @region is considered empty. + + + whether the @region is empty. + + + + + a #GtkSourceRegion, or %NULL. + + + + + + Subtracts @region_to_subtract from @region. @region_to_subtract is not +modified. + + + + + + + a #GtkSourceRegion. + + + + the #GtkSourceRegion to subtract from + @region, or %NULL. + + + + + + Subtracts the subregion delimited by @_start and @_end from @region. + + + + + + + a #GtkSourceRegion. + + + + the start of the subregion. + + + + the end of the subregion. + + + + + + Gets a string represention of @region, for debugging purposes. + +The returned string contains the character offsets of the subregions. It +doesn't include a newline character at the end of the string. + + + a string represention of @region. Free + with g_free() when no longer needed. + + + + + a #GtkSourceRegion. + + + + + + The #GtkTextBuffer. The #GtkSourceRegion has a weak reference to the +buffer. + + + + + + + + + + + + + + + + + + + #GtkSourceRegionIter is an opaque datatype; ignore all its fields. +Initialize the iter with gtk_source_region_get_start_region_iter(). + + + + + + + + + + + + Gets the subregion at this iterator. + + + %TRUE if @start and @end have been set successfully (if non-%NULL), + or %FALSE if @iter is the end iterator or if the region is empty. + + + + + a #GtkSourceRegionIter. + + + + iterator to initialize with the subregion start, or %NULL. + + + + iterator to initialize with the subregion end, or %NULL. + + + + + + + + whether @iter is the end iterator. + + + + + a #GtkSourceRegionIter. + + + + + + Moves @iter to the next subregion. + + + %TRUE if @iter moved and is dereferenceable, or %FALSE if @iter has + been set to the end iterator. + + + + + a #GtkSourceRegionIter. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new search context, associated with @buffer, and customized with +@settings. If @settings is %NULL, a new #GtkSourceSearchSettings object will +be created, that you can retrieve with +gtk_source_search_context_get_settings(). + + + a new search context. + + + + + a #GtkSourceBuffer. + + + + a #GtkSourceSearchSettings, or %NULL. + + + + + + Synchronous backward search. It is recommended to use the asynchronous +functions instead, to not block the user interface. However, if you are sure +that the @buffer is small, this function is more convenient to use. + Use gtk_source_search_context_backward2() instead. + + + whether a match was found. + + + + + a #GtkSourceSearchContext. + + + + start of search. + + + + return location for start of match, or %NULL. + + + + return location for end of match, or %NULL. + + + + + + Synchronous backward search. It is recommended to use the asynchronous +functions instead, to not block the user interface. However, if you are sure +that the @buffer is small, this function is more convenient to use. + +The difference with gtk_source_search_context_backward() is that the +@has_wrapped_around out parameter has been added for convenience. + +If the #GtkSourceSearchSettings:wrap-around property is %FALSE, this function +doesn't try to wrap around. + +The @has_wrapped_around out parameter is set independently of whether a match +is found. So if this function returns %FALSE, @has_wrapped_around will have +the same value as the #GtkSourceSearchSettings:wrap-around property. + + + whether a match was found. + + + + + a #GtkSourceSearchContext. + + + + start of search. + + + + return location for start of match, or %NULL. + + + + return location for end of match, or %NULL. + + + + return location to know whether the + search has wrapped around, or %NULL. + + + + + + The asynchronous version of gtk_source_search_context_backward2(). + +See the documentation of gtk_source_search_context_backward2() for more +details. + +See the #GAsyncResult documentation to know how to use this function. + +If the operation is cancelled, the @callback will only be called if +@cancellable was not %NULL. gtk_source_search_context_backward_async() takes +ownership of @cancellable, so you can unref it after calling this function. + + + + + + + a #GtkSourceSearchContext. + + + + start of search. + + + + a #GCancellable, or %NULL. + + + + a #GAsyncReadyCallback to call when the operation is finished. + + + + the data to pass to the @callback function. + + + + + + Finishes a backward search started with +gtk_source_search_context_backward_async(). + Use gtk_source_search_context_backward_finish2() instead. + + + whether a match was found. + + + + + a #GtkSourceSearchContext. + + + + a #GAsyncResult. + + + + return location for start of match, or %NULL. + + + + return location for end of match, or %NULL. + + + + + + Finishes a backward search started with +gtk_source_search_context_backward_async(). + +See the documentation of gtk_source_search_context_backward2() for more +details. + + + whether a match was found. + + + + + a #GtkSourceSearchContext. + + + + a #GAsyncResult. + + + + return location for start of match, or %NULL. + + + + return location for end of match, or %NULL. + + + + return location to know whether the + search has wrapped around, or %NULL. + + + + + + Synchronous forward search. It is recommended to use the asynchronous +functions instead, to not block the user interface. However, if you are sure +that the @buffer is small, this function is more convenient to use. + Use gtk_source_search_context_forward2() instead. + + + whether a match was found. + + + + + a #GtkSourceSearchContext. + + + + start of search. + + + + return location for start of match, or %NULL. + + + + return location for end of match, or %NULL. + + + + + + Synchronous forward search. It is recommended to use the asynchronous +functions instead, to not block the user interface. However, if you are sure +that the @buffer is small, this function is more convenient to use. + +The difference with gtk_source_search_context_forward() is that the +@has_wrapped_around out parameter has been added for convenience. + +If the #GtkSourceSearchSettings:wrap-around property is %FALSE, this function +doesn't try to wrap around. + +The @has_wrapped_around out parameter is set independently of whether a match +is found. So if this function returns %FALSE, @has_wrapped_around will have +the same value as the #GtkSourceSearchSettings:wrap-around property. + + + whether a match was found. + + + + + a #GtkSourceSearchContext. + + + + start of search. + + + + return location for start of match, or %NULL. + + + + return location for end of match, or %NULL. + + + + return location to know whether the + search has wrapped around, or %NULL. + + + + + + The asynchronous version of gtk_source_search_context_forward2(). + +See the documentation of gtk_source_search_context_forward2() for more +details. + +See the #GAsyncResult documentation to know how to use this function. + +If the operation is cancelled, the @callback will only be called if +@cancellable was not %NULL. gtk_source_search_context_forward_async() takes +ownership of @cancellable, so you can unref it after calling this function. + + + + + + + a #GtkSourceSearchContext. + + + + start of search. + + + + a #GCancellable, or %NULL. + + + + a #GAsyncReadyCallback to call when the operation is finished. + + + + the data to pass to the @callback function. + + + + + + Finishes a forward search started with +gtk_source_search_context_forward_async(). + Use gtk_source_search_context_forward_finish2() instead. + + + whether a match was found. + + + + + a #GtkSourceSearchContext. + + + + a #GAsyncResult. + + + + return location for start of match, or %NULL. + + + + return location for end of match, or %NULL. + + + + + + Finishes a forward search started with +gtk_source_search_context_forward_async(). + +See the documentation of gtk_source_search_context_forward2() for more +details. + + + whether a match was found. + + + + + a #GtkSourceSearchContext. + + + + a #GAsyncResult. + + + + return location for start of match, or %NULL. + + + + return location for end of match, or %NULL. + + + + return location to know whether the + search has wrapped around, or %NULL. + + + + + + + + the associated buffer. + + + + + a #GtkSourceSearchContext. + + + + + + + + whether to highlight the search occurrences. + + + + + a #GtkSourceSearchContext. + + + + + + + + the #GtkSourceStyle to apply on search matches. + + + + + a #GtkSourceSearchContext. + + + + + + Gets the position of a search occurrence. If the buffer is not already fully +scanned, the position may be unknown, and -1 is returned. If 0 is returned, +it means that this part of the buffer has already been scanned, and that +@match_start and @match_end don't delimit an occurrence. + + + the position of the search occurrence. The first occurrence has the +position 1 (not 0). Returns 0 if @match_start and @match_end don't delimit +an occurrence. Returns -1 if the position is not yet known. + + + + + a #GtkSourceSearchContext. + + + + the start of the occurrence. + + + + the end of the occurrence. + + + + + + Gets the total number of search occurrences. If the buffer is not already +fully scanned, the total number of occurrences is unknown, and -1 is +returned. + + + the total number of search occurrences, or -1 if unknown. + + + + + a #GtkSourceSearchContext. + + + + + + Regular expression patterns must follow certain rules. If +#GtkSourceSearchSettings:search-text breaks a rule, the error can be retrieved +with this function. The error domain is #G_REGEX_ERROR. + +Free the return value with g_error_free(). + + + the #GError, or %NULL if the pattern is valid. + + + + + a #GtkSourceSearchContext. + + + + + + + + the search settings. + + + + + a #GtkSourceSearchContext. + + + + + + Replaces a search match by another text. If @match_start and @match_end +doesn't correspond to a search match, %FALSE is returned. + +For a regular expression replacement, you can check if @replace is valid by +calling g_regex_check_replacement(). The @replace text can contain +backreferences; read the g_regex_replace() documentation for more details. + Use gtk_source_search_context_replace2() instead. + + + whether the match has been replaced. + + + + + a #GtkSourceSearchContext. + + + + the start of the match to replace. + + + + the end of the match to replace. + + + + the replacement text. + + + + the length of @replace in bytes, or -1. + + + + + + Replaces a search match by another text. If @match_start and @match_end +doesn't correspond to a search match, %FALSE is returned. + +Unlike with gtk_source_search_context_replace(), the @match_start and +@match_end iters are revalidated to point to the replacement text boundaries. + +For a regular expression replacement, you can check if @replace is valid by +calling g_regex_check_replacement(). The @replace text can contain +backreferences; read the g_regex_replace() documentation for more details. + + + whether the match has been replaced. + + + + + a #GtkSourceSearchContext. + + + + the start of the match to replace. + + + + the end of the match to replace. + + + + the replacement text. + + + + the length of @replace in bytes, or -1. + + + + + + Replaces all search matches by another text. It is a synchronous function, so +it can block the user interface. + +For a regular expression replacement, you can check if @replace is valid by +calling g_regex_check_replacement(). The @replace text can contain +backreferences; read the g_regex_replace() documentation for more details. + + + the number of replaced matches. + + + + + a #GtkSourceSearchContext. + + + + the replacement text. + + + + the length of @replace in bytes, or -1. + + + + + + Enables or disables the search occurrences highlighting. + + + + + + + a #GtkSourceSearchContext. + + + + the setting. + + + + + + Set the style to apply on search matches. If @match_style is %NULL, default +theme's scheme 'match-style' will be used. +To enable or disable the search highlighting, use +gtk_source_search_context_set_highlight(). + + + + + + + a #GtkSourceSearchContext. + + + + a #GtkSourceStyle, or %NULL. + + + + + + Associate a #GtkSourceSearchSettings with the search context. If @settings is +%NULL, a new one will be created. + +The search context holds a reference to @settings. + The #GtkSourceSearchContext:settings property will become a +construct-only property in a future version. Create a new +#GtkSourceSearchContext instead, or change the #GtkSourceSearchSettings +properties. When the #GtkSourceSearchContext:settings property will become +construct-only, it will be possible to simplify some code that needed to +listen to the notify::settings signal. + + + + + + + a #GtkSourceSearchContext. + + + + the new #GtkSourceSearchSettings, or %NULL. + + + + + + The #GtkSourceBuffer associated to the search context. + + + + Highlight the search occurrences. + + + + A #GtkSourceStyle, or %NULL for theme's scheme default style. + + + + The total number of search occurrences. If the search is disabled, +the value is 0. If the buffer is not already fully scanned, the value +is -1. + + + + If the regex search pattern doesn't follow all the rules, this +property will be set. If the pattern is valid, the value is %NULL. + +Free with g_error_free(). + + + + The #GtkSourceSearchSettings associated to the search context. + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new search settings object. + + + a new search settings object. + + + + + + + whether to search at word boundaries. + + + + + a #GtkSourceSearchSettings. + + + + + + + + whether the search is case sensitive. + + + + + a #GtkSourceSearchSettings. + + + + + + + + whether to search by regular expressions. + + + + + a #GtkSourceSearchSettings. + + + + + + Gets the text to search. The return value must not be freed. + +You may be interested to call gtk_source_utils_escape_search_text() after +this function. + + + the text to search, or %NULL if the search is disabled. + + + + + a #GtkSourceSearchSettings. + + + + + + + + whether to wrap around the search. + + + + + a #GtkSourceSearchSettings. + + + + + + Change whether the search is done at word boundaries. If @at_word_boundaries +is %TRUE, a search match must start and end a word. The match can span +multiple words. See also gtk_text_iter_starts_word() and +gtk_text_iter_ends_word(). + + + + + + + a #GtkSourceSearchSettings. + + + + the setting. + + + + + + Enables or disables the case sensitivity for the search. + + + + + + + a #GtkSourceSearchSettings. + + + + the setting. + + + + + + Enables or disables whether to search by regular expressions. +If enabled, the #GtkSourceSearchSettings:search-text property contains the +pattern of the regular expression. + +#GtkSourceSearchContext uses #GRegex when regex search is enabled. See the +[Regular expression syntax](https://developer.gnome.org/glib/stable/glib-regex-syntax.html) +page in the GLib reference manual. + + + + + + + a #GtkSourceSearchSettings. + + + + the setting. + + + + + + Sets the text to search. If @search_text is %NULL or is empty, the search +will be disabled. A copy of @search_text will be made, so you can safely free +@search_text after a call to this function. + +You may be interested to call gtk_source_utils_unescape_search_text() before +this function. + + + + + + + a #GtkSourceSearchSettings. + + + + the nul-terminated text to search, or %NULL to disable the search. + + + + + + Enables or disables the wrap around search. If @wrap_around is %TRUE, the +forward search continues at the beginning of the buffer if no search +occurrences are found. Similarly, the backward search continues to search at +the end of the buffer. + + + + + + + a #GtkSourceSearchSettings. + + + + the setting. + + + + + + If %TRUE, a search match must start and end a word. The match can +span multiple words. + + + + Whether the search is case sensitive. + + + + Search by regular expressions with +#GtkSourceSearchSettings:search-text as the pattern. + + + + A search string, or %NULL if the search is disabled. If the regular +expression search is enabled, #GtkSourceSearchSettings:search-text is +the pattern. + + + + For a forward search, continue at the beginning of the buffer if no +search occurrence is found. For a backward search, continue at the +end of the buffer. + + + + + + + + + + + + + + + + + + + + + + + + + + smart-home-end disabled. + + + move to the first/last +non-whitespace character on the first press of the HOME/END keys and +to the beginning/end of the line on the second press. + + + move to the beginning/end of the +line on the first press of the HOME/END keys and to the first/last +non-whitespace character on the second press. + + + always move to the first/last +non-whitespace character when the HOME/END keys are pressed. + + + + + no flags specified + + + case sensitive sort + + + sort in reverse order + + + remove duplicates + + + + + + Creates a new #GtkSourceSpaceDrawer object. Useful for storing space drawing +settings independently of a #GtkSourceView. + + + a new #GtkSourceSpaceDrawer. + + + + + Binds the #GtkSourceSpaceDrawer:matrix property to a #GSettings key. + +The #GSettings key must be of the same type as the +#GtkSourceSpaceDrawer:matrix property, that is, `"au"`. + +The g_settings_bind() function cannot be used, because the default GIO +mapping functions don't support #GVariant properties (maybe it will be +supported by a future GIO version, in which case this function can be +deprecated). + + + + + + + a #GtkSourceSpaceDrawer object. + + + + a #GSettings object. + + + + the @settings key to bind. + + + + flags for the binding. + + + + + + + + whether the #GtkSourceSpaceDrawer:matrix property is enabled. + + + + + a #GtkSourceSpaceDrawer. + + + + + + Gets the value of the #GtkSourceSpaceDrawer:matrix property, as a #GVariant. +An empty array can be returned in case the matrix is a zero matrix. + +The gtk_source_space_drawer_get_types_for_locations() function may be more +convenient to use. + + + the #GtkSourceSpaceDrawer:matrix value as a new floating #GVariant + instance. + + + + + a #GtkSourceSpaceDrawer. + + + + + + If only one location is specified, this function returns what kind of +white spaces are drawn at that location. The value is retrieved from the +#GtkSourceSpaceDrawer:matrix property. + +If several locations are specified, this function returns the logical AND for +those locations. Which means that if a certain kind of white space is present +in the return value, then that kind of white space is drawn at all the +specified @locations. + + + a combination of #GtkSourceSpaceTypeFlags. + + + + + a #GtkSourceSpaceDrawer. + + + + one or several #GtkSourceSpaceLocationFlags. + + + + + + Sets whether the #GtkSourceSpaceDrawer:matrix property is enabled. + + + + + + + a #GtkSourceSpaceDrawer. + + + + the new value. + + + + + + Sets a new value to the #GtkSourceSpaceDrawer:matrix property, as a +#GVariant. If @matrix is %NULL, then an empty array is set. + +If @matrix is floating, it is consumed. + +The gtk_source_space_drawer_set_types_for_locations() function may be more +convenient to use. + + + + + + + a #GtkSourceSpaceDrawer. + + + + the new matrix value, or %NULL. + + + + + + Modifies the #GtkSourceSpaceDrawer:matrix property at the specified +@locations. + + + + + + + a #GtkSourceSpaceDrawer. + + + + one or several #GtkSourceSpaceLocationFlags. + + + + a combination of #GtkSourceSpaceTypeFlags. + + + + + + Whether the #GtkSourceSpaceDrawer:matrix property is enabled. + + + + The :matrix property is a #GVariant property to specify where and +what kind of white spaces to draw. + +The #GVariant is of type `"au"`, an array of unsigned integers. Each +integer is a combination of #GtkSourceSpaceTypeFlags. There is one +integer for each #GtkSourceSpaceLocationFlags, in the same order as +they are defined in the enum (%GTK_SOURCE_SPACE_LOCATION_NONE and +%GTK_SOURCE_SPACE_LOCATION_ALL are not taken into account). + +If the array is shorter than the number of locations, then the value +for the missing locations will be %GTK_SOURCE_SPACE_TYPE_NONE. + +By default, %GTK_SOURCE_SPACE_TYPE_ALL is set for all locations. + + + + + + + + + + + + + + + + + + + + + + + + + #GtkSourceSpaceLocationFlags contains flags for white space locations. + +If a line contains only white spaces (no text), the white spaces match both +%GTK_SOURCE_SPACE_LOCATION_LEADING and %GTK_SOURCE_SPACE_LOCATION_TRAILING. + + No flags. + + + Leading white spaces on a line, i.e. the + indentation. + + + White spaces inside a line of text. + + + Trailing white spaces on a line. + + + White spaces anywhere. + + + + #GtkSourceSpaceTypeFlags contains flags for white space types. + + No flags. + + + Space character. + + + Tab character. + + + Line break character. If the + #GtkSourceBuffer:implicit-trailing-newline property is %TRUE, + #GtkSourceSpaceDrawer also draws a line break at the end of the buffer. + + + Non-breaking space character. + + + All white spaces. + + + + + + This function modifies the #GtkTextTag properties that are related to the +#GtkSourceStyle properties. Other #GtkTextTag properties are left untouched. + +If @style is non-%NULL, applies @style to @tag. + +If @style is %NULL, the related *-set properties of #GtkTextTag are set to +%FALSE. + + + + + + + a #GtkSourceStyle to apply, or %NULL. + + + + a #GtkTextTag to apply styles to. + + + + + + Creates a copy of @style, that is a new #GtkSourceStyle instance which +has the same attributes set. + + + copy of @style, call g_object_unref() +when you are done with it. + + + + + a #GtkSourceStyle structure to copy. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use pango-underline. + + + + + + + + + + + + + + + + + + + + + a +%NULL-terminated array containing the @scheme authors or %NULL if +no author is specified by the style scheme. + + + + + + + a #GtkSourceStyleScheme. + + + + + + + + @scheme description (if defined), or %NULL. + + + + + a #GtkSourceStyleScheme. + + + + + + + + @scheme file name if the scheme was created +parsing a style scheme file or %NULL in the other cases. + + + + + a #GtkSourceStyleScheme. + + + + + + + + @scheme id. + + + + + a #GtkSourceStyleScheme. + + + + + + + + @scheme name. + + + + + a #GtkSourceStyleScheme. + + + + + + + + style which corresponds to @style_id in +the @scheme, or %NULL when no style with this name found. It is owned by +@scheme and may not be unref'ed. + + + + + a #GtkSourceStyleScheme. + + + + id of the style to retrieve. + + + + + + Style scheme description, a translatable string to present to the user. + + + + Style scheme filename or %NULL. + + + + Style scheme id, a unique string used to identify the style scheme +in #GtkSourceStyleSchemeManager. + + + + Style scheme name, a translatable string to present to the user. + + + + + + + + + + + + + Gets the currently-selected scheme. + + + the currently-selected scheme. + + + + + a #GtkSourceStyleSchemeChooser + + + + + + Sets the scheme. + + + + + + + a #GtkSourceStyleSchemeChooser + + + + a #GtkSourceStyleScheme + + + + + + Gets the currently-selected scheme. + + + the currently-selected scheme. + + + + + a #GtkSourceStyleSchemeChooser + + + + + + Sets the scheme. + + + + + + + a #GtkSourceStyleSchemeChooser + + + + a #GtkSourceStyleScheme + + + + + + The :style-scheme property contains the currently selected style +scheme. The property can be set to change +the current selection programmatically. + + + + + + + + + + + + Creates a new #GtkSourceStyleSchemeChooserButton. + + + a new #GtkSourceStyleSchemeChooserButton. + + + + + + + + + + + + + + + + + + + + + + + the currently-selected scheme. + + + + + a #GtkSourceStyleSchemeChooser + + + + + + + + + + + + + + a #GtkSourceStyleSchemeChooser + + + + a #GtkSourceStyleScheme + + + + + + + + + + + + + + + + + + Creates a new #GtkSourceStyleSchemeChooserWidget. + + + a new #GtkSourceStyleSchemeChooserWidget. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new style manager. If you do not need more than one style +manager then use gtk_source_style_scheme_manager_get_default() instead. + + + a new #GtkSourceStyleSchemeManager. + + + + + Returns the default #GtkSourceStyleSchemeManager instance. + + + a #GtkSourceStyleSchemeManager. Return value +is owned by GtkSourceView library and must not be unref'ed. + + + + + Appends @path to the list of directories where the @manager looks for +style scheme files. +See gtk_source_style_scheme_manager_set_search_path() for details. + + + + + + + a #GtkSourceStyleSchemeManager. + + + + a directory or a filename. + + + + + + Mark any currently cached information about the available style scehems +as invalid. All the available style schemes will be reloaded next time +the @manager is accessed. + + + + + + + a #GtkSourceStyleSchemeManager. + + + + + + Looks up style scheme by id. + + + a #GtkSourceStyleScheme object. Returned value is owned by +@manager and must not be unref'ed. + + + + + a #GtkSourceStyleSchemeManager. + + + + style scheme id to find. + + + + + + Returns the ids of the available style schemes. + + + +a %NULL-terminated array of strings containing the ids of the available +style schemes or %NULL if no style scheme is available. +The array is sorted alphabetically according to the scheme name. +The array is owned by the @manager and must not be modified. + + + + + + + a #GtkSourceStyleSchemeManager. + + + + + + Returns the current search path for the @manager. +See gtk_source_style_scheme_manager_set_search_path() for details. + + + a %NULL-terminated array +of string containing the search path. +The array is owned by the @manager and must not be modified. + + + + + + + a #GtkSourceStyleSchemeManager. + + + + + + Prepends @path to the list of directories where the @manager looks +for style scheme files. +See gtk_source_style_scheme_manager_set_search_path() for details. + + + + + + + a #GtkSourceStyleSchemeManager. + + + + a directory or a filename. + + + + + + Sets the list of directories where the @manager looks for +style scheme files. +If @path is %NULL, the search path is reset to default. + + + + + + + a #GtkSourceStyleSchemeManager. + + + + +a %NULL-terminated array of strings or %NULL. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a #GtkSourceTag. Configure the tag using object arguments, +i.e. using g_object_set(). + +For usual cases, gtk_source_buffer_create_source_tag() is more convenient to +use. + + + a new #GtkSourceTag. + + + + + tag name, or %NULL. + + + + + + Whether to draw white spaces. This property takes precedence over the value +defined by the GtkSourceSpaceDrawer's #GtkSourceSpaceDrawer:matrix property +(only where the tag is applied). + +Setting this property also changes #GtkSourceTag:draw-spaces-set to +%TRUE. + + + + Whether the #GtkSourceTag:draw-spaces property is set and must be +taken into account. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Begin a not undoable action on the buffer. All changes between this call +and the call to gtk_source_undo_manager_end_not_undoable_action() cannot +be undone. This function should be re-entrant. + + + + + + + a #GtkSourceUndoManager. + + + + + + Get whether there are redo operations available. + + + %TRUE if there are redo operations available, %FALSE otherwise + + + + + a #GtkSourceUndoManager. + + + + + + Emits the #GtkSourceUndoManager::can-redo-changed signal. + + + + + + + a #GtkSourceUndoManager. + + + + + + Get whether there are undo operations available. + + + %TRUE if there are undo operations available, %FALSE otherwise + + + + + a #GtkSourceUndoManager. + + + + + + Emits the #GtkSourceUndoManager::can-undo-changed signal. + + + + + + + a #GtkSourceUndoManager. + + + + + + Ends a not undoable action on the buffer. + + + + + + + a #GtkSourceUndoManager. + + + + + + Perform a single redo. Calling this function when there are no redo operations +available is an error. Use gtk_source_undo_manager_can_redo() to find out +if there are redo operations available. + + + + + + + a #GtkSourceUndoManager. + + + + + + Perform a single undo. Calling this function when there are no undo operations +available is an error. Use gtk_source_undo_manager_can_undo() to find out +if there are undo operations available. + + + + + + + a #GtkSourceUndoManager. + + + + + + Begin a not undoable action on the buffer. All changes between this call +and the call to gtk_source_undo_manager_end_not_undoable_action() cannot +be undone. This function should be re-entrant. + + + + + + + a #GtkSourceUndoManager. + + + + + + Get whether there are redo operations available. + + + %TRUE if there are redo operations available, %FALSE otherwise + + + + + a #GtkSourceUndoManager. + + + + + + Emits the #GtkSourceUndoManager::can-redo-changed signal. + + + + + + + a #GtkSourceUndoManager. + + + + + + Get whether there are undo operations available. + + + %TRUE if there are undo operations available, %FALSE otherwise + + + + + a #GtkSourceUndoManager. + + + + + + Emits the #GtkSourceUndoManager::can-undo-changed signal. + + + + + + + a #GtkSourceUndoManager. + + + + + + Ends a not undoable action on the buffer. + + + + + + + a #GtkSourceUndoManager. + + + + + + Perform a single redo. Calling this function when there are no redo operations +available is an error. Use gtk_source_undo_manager_can_redo() to find out +if there are redo operations available. + + + + + + + a #GtkSourceUndoManager. + + + + + + Perform a single undo. Calling this function when there are no undo operations +available is an error. Use gtk_source_undo_manager_can_undo() to find out +if there are undo operations available. + + + + + + + a #GtkSourceUndoManager. + + + + + + Emitted when the ability to redo has changed. + + + + + + Emitted when the ability to undo has changed. + + + + + + + + + + + + + + + %TRUE if there are undo operations available, %FALSE otherwise + + + + + a #GtkSourceUndoManager. + + + + + + + + + + %TRUE if there are redo operations available, %FALSE otherwise + + + + + a #GtkSourceUndoManager. + + + + + + + + + + + + + + a #GtkSourceUndoManager. + + + + + + + + + + + + + + a #GtkSourceUndoManager. + + + + + + + + + + + + + + a #GtkSourceUndoManager. + + + + + + + + + + + + + + a #GtkSourceUndoManager. + + + + + + + + + + + + + + a #GtkSourceUndoManager. + + + + + + + + + + + + + + a #GtkSourceUndoManager. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #GtkSourceView. + +By default, an empty #GtkSourceBuffer will be lazily created and can be +retrieved with gtk_text_view_get_buffer(). + +If you want to specify your own buffer, either override the +#GtkTextViewClass create_buffer factory method, or use +gtk_source_view_new_with_buffer(). + + + a new #GtkSourceView. + + + + + Creates a new #GtkSourceView widget displaying the buffer +@buffer. One buffer can be shared among many widgets. + + + a new #GtkSourceView. + + + + + a #GtkSourceBuffer. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns whether auto-indentation of text is enabled. + + + %TRUE if auto indentation is enabled. + + + + + a #GtkSourceView. + + + + + + Returns the #GtkSourceBackgroundPatternType specifying if and how +the background pattern should be displayed for this @view. + + + the #GtkSourceBackgroundPatternType. + + + + + a #GtkSourceView + + + + + + Gets the #GtkSourceCompletion associated with @view. The returned object is +guaranteed to be the same for the lifetime of @view. Each #GtkSourceView +object has a different #GtkSourceCompletion. + + + the #GtkSourceCompletion associated with @view. + + + + + a #GtkSourceView. + + + + + + Returns the #GtkSourceDrawSpacesFlags specifying if and how spaces +should be displayed for this @view. + Use gtk_source_space_drawer_get_types_for_locations() +instead. + + + the #GtkSourceDrawSpacesFlags, 0 if no spaces should be drawn. + + + + + a #GtkSourceView + + + + + + Returns the #GtkSourceGutter object associated with @window_type for @view. +Only GTK_TEXT_WINDOW_LEFT and GTK_TEXT_WINDOW_RIGHT are supported, +respectively corresponding to the left and right gutter. The line numbers +and mark category icons are rendered in the left gutter. + + + the #GtkSourceGutter. + + + + + a #GtkSourceView. + + + + the gutter window type. + + + + + + Returns whether the current line is highlighted. + + + %TRUE if the current line is highlighted. + + + + + a #GtkSourceView. + + + + + + Returns whether when the tab key is pressed the current selection +should get indented instead of replaced with the \t character. + + + %TRUE if the selection is indented when tab is pressed. + + + + + a #GtkSourceView. + + + + + + Returns the number of spaces to use for each step of indent. +See gtk_source_view_set_indent_width() for details. + + + indent width. + + + + + a #GtkSourceView. + + + + + + Returns whether when inserting a tabulator character it should +be replaced by a group of space characters. + + + %TRUE if spaces are inserted instead of tabs. + + + + + a #GtkSourceView. + + + + + + Gets attributes and priority for the @category. + + + #GtkSourceMarkAttributes for the @category. +The object belongs to @view, so it must not be unreffed. + + + + + a #GtkSourceView. + + + + the category. + + + + place where priority of the category will be stored. + + + + + + Gets the position of the right margin in the given @view. + + + the position of the right margin. + + + + + a #GtkSourceView. + + + + + + Returns whether line marks are displayed beside the text. + + + %TRUE if the line marks are displayed. + + + + + a #GtkSourceView. + + + + + + Returns whether line numbers are displayed beside the text. + + + %TRUE if the line numbers are displayed. + + + + + a #GtkSourceView. + + + + + + Returns whether a right margin is displayed. + + + %TRUE if the right margin is shown. + + + + + a #GtkSourceView. + + + + + + Returns %TRUE if pressing the Backspace key will try to delete spaces +up to the previous tab stop. + + + %TRUE if smart Backspace handling is enabled. + + + + + a #GtkSourceView. + + + + + + Returns a #GtkSourceSmartHomeEndType end value specifying +how the cursor will move when HOME and END keys are pressed. + + + a #GtkSourceSmartHomeEndType value. + + + + + a #GtkSourceView. + + + + + + Gets the #GtkSourceSpaceDrawer associated with @view. The returned object is +guaranteed to be the same for the lifetime of @view. Each #GtkSourceView +object has a different #GtkSourceSpaceDrawer. + + + the #GtkSourceSpaceDrawer associated with @view. + + + + + a #GtkSourceView. + + + + + + Returns the width of tabulation in characters. + + + width of tab. + + + + + a #GtkSourceView. + + + + + + Determines the visual column at @iter taking into consideration the +#GtkSourceView:tab-width of @view. + + + the visual column at @iter. + + + + + a #GtkSourceView. + + + + a position in @view. + + + + + + Inserts one indentation level at the beginning of the specified lines. The +empty lines are not indented. + + + + + + + a #GtkSourceView. + + + + #GtkTextIter of the first line to indent + + + + #GtkTextIter of the last line to indent + + + + + + If %TRUE auto-indentation of text is enabled. + +When Enter is pressed to create a new line, the auto-indentation inserts the +same indentation as the previous line. This is <emphasis>not</emphasis> a +"smart indentation" where an indentation level is added or removed depending +on the context. + + + + + + + a #GtkSourceView. + + + + whether to enable auto indentation. + + + + + + Set if and how the background pattern should be displayed. + + + + + + + a #GtkSourceView. + + + + the #GtkSourceBackgroundPatternType. + + + + + + Set if and how the spaces should be visualized. Specifying @flags as 0 will +disable display of spaces. + +For a finer-grained method, there is also the GtkSourceTag's +#GtkSourceTag:draw-spaces property. + Use gtk_source_space_drawer_set_types_for_locations() +instead. + + + + + + + a #GtkSourceView. + + + + #GtkSourceDrawSpacesFlags specifing how white spaces should +be displayed + + + + + + If @highlight is %TRUE the current line will be highlighted. + + + + + + + a #GtkSourceView. + + + + whether to highlight the current line. + + + + + + If %TRUE, when the tab key is pressed when several lines are selected, the +selected lines are indented of one level instead of being replaced with a \t +character. Shift+Tab unindents the selection. + +If the first or last line is not selected completely, it is also indented or +unindented. + +When the selection doesn't span several lines, the tab key always replaces +the selection with a normal \t character. + + + + + + + a #GtkSourceView. + + + + whether to indent a block when tab is pressed. + + + + + + Sets the number of spaces to use for each step of indent when the tab key is +pressed. If @width is -1, the value of the #GtkSourceView:tab-width property +will be used. + +The #GtkSourceView:indent-width interacts with the +#GtkSourceView:insert-spaces-instead-of-tabs property and +#GtkSourceView:tab-width. An example will be clearer: if the +#GtkSourceView:indent-width is 4 and +#GtkSourceView:tab-width is 8 and +#GtkSourceView:insert-spaces-instead-of-tabs is %FALSE, then pressing the tab +key at the beginning of a line will insert 4 spaces. So far so good. Pressing +the tab key a second time will remove the 4 spaces and insert a \t character +instead (since #GtkSourceView:tab-width is 8). On the other hand, if +#GtkSourceView:insert-spaces-instead-of-tabs is %TRUE, the second tab key +pressed will insert 4 more spaces for a total of 8 spaces in the +#GtkTextBuffer. + +The test-widget program (available in the GtkSourceView repository) may be +useful to better understand the indentation settings (enable the space +drawing!). + + + + + + + a #GtkSourceView. + + + + indent width in characters. + + + + + + If %TRUE a tab key pressed is replaced by a group of space characters. Of +course it is still possible to insert a real \t programmatically with the +#GtkTextBuffer API. + + + + + + + a #GtkSourceView. + + + + whether to insert spaces instead of tabs. + + + + + + Sets attributes and priority for the @category. + + + + + + + a #GtkSourceView. + + + + the category. + + + + mark attributes. + + + + priority of the category. + + + + + + Sets the position of the right margin in the given @view. + + + + + + + a #GtkSourceView. + + + + the width in characters where to position the right margin. + + + + + + If %TRUE line marks will be displayed beside the text. + + + + + + + a #GtkSourceView. + + + + whether line marks should be displayed. + + + + + + If %TRUE line numbers will be displayed beside the text. + + + + + + + a #GtkSourceView. + + + + whether line numbers should be displayed. + + + + + + If %TRUE a right margin is displayed. + + + + + + + a #GtkSourceView. + + + + whether to show a right margin. + + + + + + When set to %TRUE, pressing the Backspace key will try to delete spaces +up to the previous tab stop. + + + + + + + a #GtkSourceView. + + + + whether to enable smart Backspace handling. + + + + + + Set the desired movement of the cursor when HOME and END keys +are pressed. + + + + + + + a #GtkSourceView. + + + + the desired behavior among #GtkSourceSmartHomeEndType. + + + + + + Sets the width of tabulation in characters. The #GtkTextBuffer still contains +\t characters, but they can take a different visual width in a #GtkSourceView +widget. + + + + + + + a #GtkSourceView. + + + + width of tab in characters. + + + + + + Removes one indentation level at the beginning of the +specified lines. + + + + + + + a #GtkSourceView. + + + + #GtkTextIter of the first line to indent + + + + #GtkTextIter of the last line to indent + + + + + + + + + Draw a specific background pattern on the view. + + + + The completion object associated with the view + + + + Set if and how the spaces should be visualized. + +For a finer-grained method, there is also the GtkSourceTag's +#GtkSourceTag:draw-spaces property. + Use the #GtkSourceSpaceDrawer:matrix property +instead. + + + + + + + + + + Width of an indentation step expressed in number of spaces. + + + + + + + Position of the right margin. + + + + Whether to display line mark pixbufs + + + + Whether to display line numbers + + + + Whether to display the right margin. + + + + Whether smart Backspace should be used. + + + + Set the behavior of the HOME and END keys. + + + + The #GtkSourceSpaceDrawer object associated with the view. + + + + Width of a tab character expressed in number of spaces. + + + + + + + + + + Keybinding signal to change case of the text at the current cursor position. + + + + + + the case to use + + + + + + Keybinding signal to edit a number at the current cursor position. + + + + + + the number to add to the number at the current position + + + + + + Keybinding signal to join the lines currently selected. + + + + + + Emitted when a line mark has been activated (for instance when there +was a button press in the line marks gutter). You can use @iter to +determine on which line the activation took place. + + + + + + a #GtkTextIter + + + + the #GdkEvent that activated the event + + + + + + The ::move-lines signal is a keybinding which gets emitted +when the user initiates moving a line. The default binding key +is Alt+Up/Down arrow. And moves the currently selected lines, +or the current line by @count. For the moment, only +@count of -1 or 1 is valid. + +The @copy parameter is deprecated, it has never been used by +GtkSourceView (the value is always %FALSE) and was buggy. + + + + + + %TRUE if the line should be copied, %FALSE if it should be + moved. This parameter is deprecated and will be removed in a later + version, it should be always %FALSE. + + + + the number of lines to move over. Only 1 and -1 are + supported. + + + + + + Keybinding signal to move the cursor to the matching bracket. + + + + + + %TRUE if the move should extend the selection + + + + + + The ::move-words signal is a keybinding which gets emitted +when the user initiates moving a word. The default binding key +is Alt+Left/Right Arrow and moves the current selection, or the current +word by one word. + + + + + + the number of words to move over + + + + + + + + + + + The ::show-completion signal is a key binding signal which gets +emitted when the user requests a completion, by pressing +<keycombo><keycap>Control</keycap><keycap>space</keycap></keycombo>. + +This will create a #GtkSourceCompletionContext with the activation +type as %GTK_SOURCE_COMPLETION_ACTIVATION_USER_REQUESTED. + +Applications should not connect to it, but may emit it with +g_signal_emit_by_name() if they need to activate the completion by +another means, for example with another key binding or a menu entry. + + + + + + Emitted when a the cursor was moved according to the smart home +end setting. The signal is emitted after the cursor is moved, but +during the GtkTextView::move-cursor action. This can be used to find +out whether the cursor was moved by a normal home/end or by a smart +home/end. + + + + + + a #GtkTextIter + + + + the count + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the gutter position of the lines +renderer + + + the gutter position of the marks +renderer + + + + + + + + + + + + Gets all encodings. + + + a list of +all #GtkSourceEncoding's. Free with g_slist_free(). + + + + + + + Gets the #GtkSourceEncoding for the current locale. See also g_get_charset(). + + + the current locale encoding. + + + + + Gets the list of default candidate encodings to try when loading a file. See +gtk_source_file_loader_set_candidate_encodings(). + +This function returns a different list depending on the current locale (i.e. +language, country and default encoding). The UTF-8 encoding and the current +locale encoding are guaranteed to be present in the returned list. + + + the list of +default candidate encodings. Free with g_slist_free(). + + + + + + + Gets a #GtkSourceEncoding from a character set such as "UTF-8" or +"ISO-8859-1". + + + the corresponding #GtkSourceEncoding, or %NULL +if not found. + + + + + a character set. + + + + + + + + the UTF-8 encoding. + + + + + + + + + + + + + + + Use this function to escape the following characters: `\n`, `\r`, `\t` and `\`. + +For a regular expression search, use g_regex_escape_string() instead. + +One possible use case is to take the #GtkTextBuffer's selection and put it in a +search entry. The selection can contain tabulations, newlines, etc. So it's +better to escape those special characters to better fit in the search entry. + +See also: gtk_source_utils_unescape_search_text(). + +<warning> +Warning: the escape and unescape functions are not reciprocal! For example, +escape (unescape (\)) = \\. So avoid cycles such as: search entry -> unescape +-> search settings -> escape -> search entry. The original search entry text +may be modified. +</warning> + + + the escaped @text. + + + + + the text to escape. + + + + + + Use this function before gtk_source_search_settings_set_search_text(), to +unescape the following sequences of characters: `\n`, `\r`, `\t` and `\\`. +The purpose is to easily write those characters in a search entry. + +Note that unescaping the search text is not needed for regular expression +searches. + +See also: gtk_source_utils_escape_search_text(). + + + the unescaped @text. + + + + + the text to unescape. + + + + + + diff --git a/gir-files/JavaScriptCore-4.0-patch.gir b/gir-files/JavaScriptCore-4.0-patch.gir new file mode 100644 index 0000000..176ceb2 --- /dev/null +++ b/gir-files/JavaScriptCore-4.0-patch.gir @@ -0,0 +1,355 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + return location for a #JSCException, or %NULL to ignore + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/JavaScriptCore-4.0.gir b/gir-files/JavaScriptCore-4.0.gir new file mode 100644 index 0000000..4d6c385 --- /dev/null +++ b/gir-files/JavaScriptCore-4.0.gir @@ -0,0 +1,3603 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + return location for a #JSCException, or %NULL to ignore + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values to specify a mode to check for syntax errors in jsc_context_check_syntax(). + + + mode to check syntax of a script + + + mode to check syntax of a module + + + + Enum values to specify the result of jsc_context_check_syntax(). + + + no errors + + + recoverable syntax error + + + irrecoverable syntax error + + + unterminated literal error + + + out of memory error + + + stack overflow error + + + + + + Add a constructor to @jsc_class. If @name is %NULL, the class name will be used. When <function>new</function> +is used with the constructor or jsc_value_constructor_call() is called, @callback is invoked receiving the +parameters and @user_data as the last parameter. When the constructor object is cleared in the #JSCClass context, +@destroy_notify is called with @user_data as parameter. + +This function creates the constructor, which needs to be added to an object as a property to be able to use it. Use +jsc_context_set_value() to make the constructor available in the global object. + +Note that the value returned by @callback is adopted by @jsc_class, and the #GDestroyNotify passed to +jsc_context_register_class() is responsible for disposing of it. + + + a #JSCValue representing the class constructor. + + + + + a #JSCClass + + + + the constructor name or %NULL + + + + a #GCallback to be called to create an instance of @jsc_class + + + + user data to pass to @callback + + + + destroy notifier for @user_data + + + + the #GType of the constructor return value + + + + the number of parameter types to follow or 0 if constructor doesn't receive parameters. + + + + a list of #GType<!-- -->s, one for each parameter. + + + + + + Add a constructor to @jsc_class. If @name is %NULL, the class name will be used. When <function>new</function> +is used with the constructor or jsc_value_constructor_call() is called, @callback is invoked receiving +a #GPtrArray of #JSCValue<!-- -->s as arguments and @user_data as the last parameter. When the constructor object +is cleared in the #JSCClass context, @destroy_notify is called with @user_data as parameter. + +This function creates the constructor, which needs to be added to an object as a property to be able to use it. Use +jsc_context_set_value() to make the constructor available in the global object. + +Note that the value returned by @callback is adopted by @jsc_class, and the #GDestroyNotify passed to +jsc_context_register_class() is responsible for disposing of it. + + + a #JSCValue representing the class constructor. + + + + + a #JSCClass + + + + the constructor name or %NULL + + + + a #GCallback to be called to create an instance of @jsc_class + + + + user data to pass to @callback + + + + destroy notifier for @user_data + + + + the #GType of the constructor return value + + + + + + Add a constructor to @jsc_class. If @name is %NULL, the class name will be used. When <function>new</function> +is used with the constructor or jsc_value_constructor_call() is called, @callback is invoked receiving the +parameters and @user_data as the last parameter. When the constructor object is cleared in the #JSCClass context, +@destroy_notify is called with @user_data as parameter. + +This function creates the constructor, which needs to be added to an object as a property to be able to use it. Use +jsc_context_set_value() to make the constructor available in the global object. + +Note that the value returned by @callback is adopted by @jsc_class, and the #GDestroyNotify passed to +jsc_context_register_class() is responsible for disposing of it. + + + a #JSCValue representing the class constructor. + + + + + a #JSCClass + + + + the constructor name or %NULL + + + + a #GCallback to be called to create an instance of @jsc_class + + + + user data to pass to @callback + + + + destroy notifier for @user_data + + + + the #GType of the constructor return value + + + + the number of parameters + + + + a list of #GType<!-- -->s, one for each parameter, or %NULL + + + + + + + + Add method with @name to @jsc_class. When the method is called by JavaScript or jsc_value_object_invoke_method(), +@callback is called receiving the class instance as first parameter, followed by the method parameters and then +@user_data as last parameter. When the method is cleared in the #JSCClass context, @destroy_notify is called with +@user_data as parameter. + +Note that the value returned by @callback must be transfer full. In case of non-refcounted boxed types, you should use +%G_TYPE_POINTER instead of the actual boxed #GType to ensure that the instance owned by #JSCClass is used. +If you really want to return a new copy of the boxed type, use #JSC_TYPE_VALUE and return a #JSCValue created +with jsc_value_new_object() that receives the copy as the instance parameter. + + + + + + + a #JSCClass + + + + the method name + + + + a #GCallback to be called to invoke method @name of @jsc_class + + + + user data to pass to @callback + + + + destroy notifier for @user_data + + + + the #GType of the method return value, or %G_TYPE_NONE if the method is void. + + + + the number of parameter types to follow or 0 if the method doesn't receive parameters. + + + + a list of #GType<!-- -->s, one for each parameter. + + + + + + Add method with @name to @jsc_class. When the method is called by JavaScript or jsc_value_object_invoke_method(), +@callback is called receiving the class instance as first parameter, followed by a #GPtrArray of #JSCValue<!-- -->s +with the method arguments and then @user_data as last parameter. When the method is cleared in the #JSCClass context, +@destroy_notify is called with @user_data as parameter. + +Note that the value returned by @callback must be transfer full. In case of non-refcounted boxed types, you should use +%G_TYPE_POINTER instead of the actual boxed #GType to ensure that the instance owned by #JSCClass is used. +If you really want to return a new copy of the boxed type, use #JSC_TYPE_VALUE and return a #JSCValue created +with jsc_value_new_object() that receives the copy as the instance parameter. + + + + + + + a #JSCClass + + + + the method name + + + + a #GCallback to be called to invoke method @name of @jsc_class + + + + user data to pass to @callback + + + + destroy notifier for @user_data + + + + the #GType of the method return value, or %G_TYPE_NONE if the method is void. + + + + + + Add method with @name to @jsc_class. When the method is called by JavaScript or jsc_value_object_invoke_method(), +@callback is called receiving the class instance as first parameter, followed by the method parameters and then +@user_data as last parameter. When the method is cleared in the #JSCClass context, @destroy_notify is called with +@user_data as parameter. + +Note that the value returned by @callback must be transfer full. In case of non-refcounted boxed types, you should use +%G_TYPE_POINTER instead of the actual boxed #GType to ensure that the instance owned by #JSCClass is used. +If you really want to return a new copy of the boxed type, use #JSC_TYPE_VALUE and return a #JSCValue created +with jsc_value_new_object() that receives the copy as the instance parameter. + + + + + + + a #JSCClass + + + + the method name + + + + a #GCallback to be called to invoke method @name of @jsc_class + + + + user data to pass to @callback + + + + destroy notifier for @user_data + + + + the #GType of the method return value, or %G_TYPE_NONE if the method is void. + + + + the number of parameter types to follow or 0 if the method doesn't receive parameters. + + + + a list of #GType<!-- -->s, one for each parameter, or %NULL + + + + + + + + Add a property with @name to @jsc_class. When the property value needs to be getted, @getter is called +receiving the the class instance as first parameter and @user_data as last parameter. When the property +value needs to be set, @setter is called receiving the the class instance as first parameter, followed +by the value to be set and then @user_data as the last parameter. When the property is cleared in the +#JSCClass context, @destroy_notify is called with @user_data as parameter. + +Note that the value returned by @getter must be transfer full. In case of non-refcounted boxed types, you should use +%G_TYPE_POINTER instead of the actual boxed #GType to ensure that the instance owned by #JSCClass is used. +If you really want to return a new copy of the boxed type, use #JSC_TYPE_VALUE and return a #JSCValue created +with jsc_value_new_object() that receives the copy as the instance parameter. + + + + + + + a #JSCClass + + + + the property name + + + + the #GType of the property value + + + + a #GCallback to be called to get the property value + + + + a #GCallback to be called to set the property value + + + + user data to pass to @getter and @setter + + + + destroy notifier for @user_data + + + + + + Get the class name of @jsc_class + + + the name of @jsc_class + + + + + a @JSCClass + + + + + + Get the parent class of @jsc_class + + + the parent class of @jsc_class + + + + + a @JSCClass + + + + + + The #JSCContext in which the class was registered. + + + + The name of the class. + + + + The parent class or %NULL in case of final classes. + + + + + + + + The type of delete_property in #JSCClassVTable. This is only required when you need to handle +external properties not added to the prototype. + + + %TRUE if handled or %FALSE to to forward the request to the parent class or prototype chain. + + + + + a #JSCClass + + + + a #JSCContext + + + + the @jsc_class instance + + + + the property name + + + + + + The type of enumerate_properties in #JSCClassVTable. This is only required when you need to handle +external properties not added to the prototype. + + + a %NULL-terminated array of strings + containing the property names, or %NULL if @instance doesn't have enumerable properties. + + + + + + + a #JSCClass + + + + a #JSCContext + + + + the @jsc_class instance + + + + + + The type of get_property in #JSCClassVTable. This is only required when you need to handle +external properties not added to the prototype. + + + a #JSCValue or %NULL to forward the request to + the parent class or prototype chain + + + + + a #JSCClass + + + + a #JSCContext + + + + the @jsc_class instance + + + + the property name + + + + + + The type of has_property in #JSCClassVTable. This is only required when you need to handle +external properties not added to the prototype. + + + %TRUE if @instance has a property with @name or %FALSE to forward the request + to the parent class or prototype chain. + + + + + a #JSCClass + + + + a #JSCContext + + + + the @jsc_class instance + + + + the property name + + + + + + The type of set_property in #JSCClassVTable. This is only required when you need to handle +external properties not added to the prototype. + + + %TRUE if handled or %FALSE to forward the request to the parent class or prototype chain. + + + + + a #JSCClass + + + + a #JSCContext + + + + the @jsc_class instance + + + + the property name + + + + the #JSCValue to set + + + + + + Virtual table for a JSCClass. This can be optionally used when registering a #JSCClass in a #JSCContext +to provide a custom implementation for the class. All virtual functions are optional and can be set to +%NULL to fallback to the default implementation. + + + a #JSCClassGetPropertyFunction for getting a property. + + + + a #JSCClassSetPropertyFunction for setting a property. + + + + a #JSCClassHasPropertyFunction for querying a property. + + + + a #JSCClassDeletePropertyFunction for deleting a property. + + + + a #JSCClassEnumeratePropertiesFunction for enumerating properties. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Create a new #JSCContext. The context is created in a new #JSCVirtualMachine. +Use jsc_context_new_with_virtual_machine() to create a new #JSCContext in an +existing #JSCVirtualMachine. + + + the newly created #JSCContext. + + + + + Create a new #JSCContext in @virtual_machine. + + + the newly created #JSCContext. + + + + + a #JSCVirtualMachine + + + + + + Get the #JSCContext that is currently executing a function. This should only be +called within a function or method callback, otherwise %NULL will be returned. + + + the #JSCContext that is currently executing. + + + + + Check the given @code in @context for syntax errors. The @line_number is the starting line number in @uri; +the value is one-based so the first line is 1. @uri and @line_number are only used to fill the @exception. +In case of errors @exception will be set to a new #JSCException with the details. You can pass %NULL to +@exception to ignore the error details. + + + a #JSCCheckSyntaxResult + + + + + a #JSCContext + + + + a JavaScript script to check + + + + length of @code, or -1 if @code is a nul-terminated string + + + + a #JSCCheckSyntaxMode + + + + the source URI + + + + the starting line number + + + + return location for a #JSCException, or %NULL to ignore + + + + + + Clear the uncaught exception in @context if any. + + + + + + + a #JSCContext + + + + + + Evaluate @code in @context. + + + a #JSCValue representing the last value generated by the script. + + + + + a #JSCContext + + + + a JavaScript script to evaluate + + + + length of @code, or -1 if @code is a nul-terminated string + + + + + + Evaluate @code and create an new object where symbols defined in @code will be added as properties, +instead of being added to @context global object. The new object is returned as @object parameter. +Similar to how jsc_value_new_object() works, if @object_instance is not %NULL @object_class must be provided too. +The @line_number is the starting line number in @uri; the value is one-based so the first line is 1. +@uri and @line_number will be shown in exceptions and they don't affect the behavior of the script. + + + a #JSCValue representing the last value generated by the script. + + + + + a #JSCContext + + + + a JavaScript script to evaluate + + + + length of @code, or -1 if @code is a nul-terminated string + + + + an object instance + + + + a #JSCClass or %NULL to use the default + + + + the source URI + + + + the starting line number + + + + return location for a #JSCValue. + + + + + + Evaluate @code in @context using @uri as the source URI. The @line_number is the starting line number +in @uri; the value is one-based so the first line is 1. @uri and @line_number will be shown in exceptions and +they don't affect the behavior of the script. + + + a #JSCValue representing the last value generated by the script. + + + + + a #JSCContext + + + + a JavaScript script to evaluate + + + + length of @code, or -1 if @code is a nul-terminated string + + + + the source URI + + + + the starting line number + + + + + + Get the last unhandled exception thrown in @context by API functions calls. + + + a #JSCException or %NULL if there isn't any + unhandled exception in the #JSCContext. + + + + + a #JSCContext + + + + + + Get a #JSCValue referencing the @context global object + + + a #JSCValue + + + + + a #JSCContext + + + + + + Get a property of @context global object with @name. + + + a #JSCValue + + + + + a #JSCContext + + + + the value name + + + + + + Get the #JSCVirtualMachine where @context was created. + + + the #JSCVirtualMachine where the #JSCContext was created. + + + + + a #JSCContext + + + + + + Remove the last #JSCExceptionHandler previously pushed to @context with +jsc_context_push_exception_handler(). + + + + + + + a #JSCContext + + + + + + Push an exception handler in @context. Whenever a JavaScript exception happens in +the #JSCContext, the given @handler will be called. The default #JSCExceptionHandler +simply calls jsc_context_throw_exception() to throw the exception to the #JSCContext. +If you don't want to catch the exception, but only get notified about it, call +jsc_context_throw_exception() in @handler like the default one does. +The last exception handler pushed is the only one used by the #JSCContext, use +jsc_context_pop_exception_handler() to remove it and set the previous one. When @handler +is removed from the context, @destroy_notify i called with @user_data as parameter. + + + + + + + a #JSCContext + + + + a #JSCExceptionHandler + + + + user data to pass to @handler + + + + destroy notifier for @user_data + + + + + + Register a custom class in @context using the given @name. If the new class inherits from +another #JSCClass, the parent should be passed as @parent_class, otherwise %NULL should be +used. The optional @vtable parameter allows to provide a custom implementation for handling +the class, for example, to handle external properties not added to the prototype. +When an instance of the #JSCClass is cleared in the context, @destroy_notify is called with +the instance as parameter. + + + a #JSCClass + + + + + a #JSCContext + + + + the class name + + + + a #JSCClass or %NULL + + + + an optional #JSCClassVTable or %NULL + + + + a destroy notifier for class instances + + + + + + Set a property of @context global object with @name and @value. + + + + + + + a #JSCContext + + + + the value name + + + + a #JSCValue + + + + + + Throw an exception to @context using the given error message. The created #JSCException +can be retrieved with jsc_context_get_exception(). + + + + + + + a #JSCContext + + + + an error message + + + + + + Throw @exception to @context. + + + + + + + a #JSCContext + + + + a #JSCException + + + + + + Throw an exception to @context using the given formatted string as error message. +The created #JSCException can be retrieved with jsc_context_get_exception(). + + + + + + + a #JSCContext + + + + the string format + + + + the parameters to insert into the format string + + + + + + Throw an exception to @context using the given error name and message. The created #JSCException +can be retrieved with jsc_context_get_exception(). + + + + + + + a #JSCContext + + + + the error name + + + + an error message + + + + + + Throw an exception to @context using the given error name and the formatted string as error message. +The created #JSCException can be retrieved with jsc_context_get_exception(). + + + + + + + a #JSCContext + + + + the error name + + + + the string format + + + + the parameters to insert into the format string + + + + + + The #JSCVirtualMachine in which the context was created. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Create a new #JSCException in @context with @message. + + + a new #JSCException. + + + + + a #JSCContext + + + + the error message + + + + + + Create a new #JSCException in @context using a formatted string +for the message. + + + a new #JSCException. + + + + + a #JSCContext + + + + the string format + + + + the parameters to insert into the format string + + + + + + Create a new #JSCException in @context using a formatted string +for the message. This is similar to jsc_exception_new_printf() +except that the arguments to the format string are passed as a va_list. + + + a new #JSCException. + + + + + a #JSCContext + + + + the string format + + + + the parameters to insert into the format string + + + + + + Create a new #JSCException in @context with @name and @message. + + + a new #JSCException. + + + + + a #JSCContext + + + + the error name + + + + the error message + + + + + + Create a new #JSCException in @context with @name and using a formatted string +for the message. + + + a new #JSCException. + + + + + a #JSCContext + + + + the error name + + + + the string format + + + + the parameters to insert into the format string + + + + + + Create a new #JSCException in @context with @name and using a formatted string +for the message. This is similar to jsc_exception_new_with_name_printf() +except that the arguments to the format string are passed as a va_list. + + + a new #JSCException. + + + + + a #JSCContext + + + + the error name + + + + the string format + + + + the parameters to insert into the format string + + + + + + Get a string with the exception backtrace. + + + the exception backtrace string or %NULL. + + + + + a #JSCException + + + + + + Get the column number at which @exception happened. + + + the column number of @exception. + + + + + a #JSCException + + + + + + Get the line number at which @exception happened. + + + the line number of @exception. + + + + + a #JSCException + + + + + + Get the error message of @exception. + + + the @exception error message. + + + + + a #JSCException + + + + + + Get the error name of @exception + + + the @exception error name. + + + + + a #JSCException + + + + + + Get the source URI of @exception. + + + the the source URI of @exception, or %NULL. + + + + + a #JSCException + + + + + + Return a report message of @exception, containing all the possible details such us +source URI, line, column and backtrace, and formatted to be printed. + + + a new string with the exception report + + + + + a #JSCException + + + + + + Get the string representation of @exception error. + + + the string representation of @exception. + + + + + a #JSCException + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Function used to handle JavaScript exceptions in a #JSCContext. + + + + + + + a #JSCContext + + + + a #JSCException + + + + user data + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Like jsc_get_major_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + Like jsc_get_micro_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + Like jsc_get_minor_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + Allows the DFG JIT to be used if %TRUE. +Option type: %JSC_OPTION_BOOLEAN +Default value: %TRUE. + + + + + Allows the FTL JIT to be used if %TRUE. +Option type: %JSC_OPTION_BOOLEAN +Default value: %TRUE. + + + + + Allows the executable pages to be allocated for JIT and thunks if %TRUE. +Option type: %JSC_OPTION_BOOLEAN +Default value: %TRUE. + + + + + Allows the LLINT to be used if %TRUE. +Option type: %JSC_OPTION_BOOLEAN +Default value: %TRUE. + + + + + Enum values for options types. + + + A #gboolean option type. + + + A #gint option type. + + + A #guint option type. + + + A #gsize options type. + + + A #gdouble options type. + + + A string option type. + + + A range string option type. + + + + Function used to iterate options. + +Not that @description string is not localized. + + + %TRUE to stop the iteration, or %FALSE otherwise + + + + + the option name + + + + the option #JSCOptionType + + + + the option description, or %NULL + + + + user data + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Create a new #JSCValue referencing an array with the given items. If @first_item_type +is %G_TYPE_NONE an empty array is created. + + + a #JSCValue. + + + + + a #JSCContext + + + + #GType of first item, or %G_TYPE_NONE + + + + value of the first item, followed optionally by more type/value pairs, followed by %G_TYPE_NONE. + + + + + + Create a new #JSCValue referencing an array with the items from @array. If @array +is %NULL or empty a new empty array will be created. Elements of @array should be +pointers to a #JSCValue. + + + a #JSCValue. + + + + + a #JSCContext + + + + a #GPtrArray + + + + + + + + Create a new #JSCValue referencing an array of strings with the items from @strv. If @array +is %NULL or empty a new empty array will be created. + + + a #JSCValue. + + + + + a #JSCContext + + + + a %NULL-terminated array of strings + + + + + + + + Create a new #JSCValue from @value + + + a #JSCValue. + + + + + a #JSCContext + + + + a #gboolean + + + + + + Create a function in @context. If @name is %NULL an anonymous function will be created. +When the function is called by JavaScript or jsc_value_function_call(), @callback is called +receiving the function parameters and then @user_data as last parameter. When the function is +cleared in @context, @destroy_notify is called with @user_data as parameter. + +Note that the value returned by @callback must be fully transferred. In case of boxed types, you could use +%G_TYPE_POINTER instead of the actual boxed #GType to ensure that the instance owned by #JSCClass is used. +If you really want to return a new copy of the boxed type, use #JSC_TYPE_VALUE and return a #JSCValue created +with jsc_value_new_object() that receives the copy as instance parameter. + + + a #JSCValue. + + + + + a #JSCContext: + + + + the function name or %NULL + + + + a #GCallback. + + + + user data to pass to @callback. + + + + destroy notifier for @user_data + + + + the #GType of the function return value, or %G_TYPE_NONE if the function is void. + + + + the number of parameter types to follow or 0 if the function doesn't receive parameters. + + + + a list of #GType<!-- -->s, one for each parameter. + + + + + + Create a function in @context. If @name is %NULL an anonymous function will be created. +When the function is called by JavaScript or jsc_value_function_call(), @callback is called +receiving an #GPtrArray of #JSCValue<!-- -->s with the arguments and then @user_data as last parameter. +When the function is cleared in @context, @destroy_notify is called with @user_data as parameter. + +Note that the value returned by @callback must be fully transferred. In case of boxed types, you could use +%G_TYPE_POINTER instead of the actual boxed #GType to ensure that the instance owned by #JSCClass is used. +If you really want to return a new copy of the boxed type, use #JSC_TYPE_VALUE and return a #JSCValue created +with jsc_value_new_object() that receives the copy as instance parameter. + + + a #JSCValue. + + + + + a #JSCContext + + + + the function name or %NULL + + + + a #GCallback. + + + + user data to pass to @callback. + + + + destroy notifier for @user_data + + + + the #GType of the function return value, or %G_TYPE_NONE if the function is void. + + + + + + Create a function in @context. If @name is %NULL an anonymous function will be created. +When the function is called by JavaScript or jsc_value_function_call(), @callback is called +receiving the function parameters and then @user_data as last parameter. When the function is +cleared in @context, @destroy_notify is called with @user_data as parameter. + +Note that the value returned by @callback must be fully transferred. In case of boxed types, you could use +%G_TYPE_POINTER instead of the actual boxed #GType to ensure that the instance owned by #JSCClass is used. +If you really want to return a new copy of the boxed type, use #JSC_TYPE_VALUE and return a #JSCValue created +with jsc_value_new_object() that receives the copy as instance parameter. + + + a #JSCValue. + + + + + a #JSCContext + + + + the function name or %NULL + + + + a #GCallback. + + + + user data to pass to @callback. + + + + destroy notifier for @user_data + + + + the #GType of the function return value, or %G_TYPE_NONE if the function is void. + + + + the number of parameters + + + + a list of #GType<!-- -->s, one for each parameter, or %NULL + + + + + + + + Create a new #JSCValue referencing <function>null</function> in @context. + + + a #JSCValue. + + + + + a #JSCContext + + + + + + Create a new #JSCValue from @number. + + + a #JSCValue. + + + + + a #JSCContext + + + + a number + + + + + + Create a new #JSCValue from @instance. If @instance is %NULL a new empty object is created. +When @instance is provided, @jsc_class must be provided too. @jsc_class takes ownership of +@instance that will be freed by the #GDestroyNotify passed to jsc_context_register_class(). + + + a #JSCValue. + + + + + a #JSCContext + + + + an object instance or %NULL + + + + the #JSCClass of @instance + + + + + + Create a new #JSCValue from @string. If you need to create a #JSCValue from a +string containing null characters, use jsc_value_new_string_from_bytes() instead. + + + a #JSCValue. + + + + + a #JSCContext + + + + a null-terminated string + + + + + + Create a new #JSCValue from @bytes. + + + a #JSCValue. + + + + + a #JSCContext + + + + a #GBytes + + + + + + Create a new #JSCValue referencing <function>undefined</function> in @context. + + + a #JSCValue. + + + + + a #JSCContext + + + + + + Invoke <function>new</function> with constructor referenced by @value. If @first_parameter_type +is %G_TYPE_NONE no parameters will be passed to the constructor. + + + a #JSCValue referencing the newly created object instance. + + + + + a #JSCValue + + + + #GType of first parameter, or %G_TYPE_NONE + + + + value of the first parameter, followed optionally by more type/value pairs, followed by %G_TYPE_NONE + + + + + + Invoke <function>new</function> with constructor referenced by @value. If @n_parameters +is 0 no parameters will be passed to the constructor. + + + a #JSCValue referencing the newly created object instance. + + + + + a #JSCValue + + + + the number of parameters + + + + the #JSCValue<!-- -->s to pass as parameters to the constructor, or %NULL + + + + + + + + Call function referenced by @value, passing the given parameters. If @first_parameter_type +is %G_TYPE_NONE no parameters will be passed to the function. + +This function always returns a #JSCValue, in case of void functions a #JSCValue referencing +<function>undefined</function> is returned + + + a #JSCValue with the return value of the function. + + + + + a #JSCValue + + + + #GType of first parameter, or %G_TYPE_NONE + + + + value of the first parameter, followed optionally by more type/value pairs, followed by %G_TYPE_NONE + + + + + + Call function referenced by @value, passing the given @parameters. If @n_parameters +is 0 no parameters will be passed to the function. + +This function always returns a #JSCValue, in case of void functions a #JSCValue referencing +<function>undefined</function> is returned + + + a #JSCValue with the return value of the function. + + + + + a #JSCValue + + + + the number of parameters + + + + the #JSCValue<!-- -->s to pass as parameters to the function, or %NULL + + + + + + + + Get the #JSCContext in which @value was created. + + + the #JSCValue context. + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is an array. + + + whether the value is an array. + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is a boolean. + + + whether the value is a boolean. + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is a constructor. + + + whether the value is a constructor. + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is a function + + + whether the value is a function. + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is <function>null</function>. + + + whether the value is null. + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is a number. + + + whether the value is a number. + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is an object. + + + whether the value is an object. + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is a string + + + whether the value is a string + + + + + a #JSCValue + + + + + + Get whether the value referenced by @value is <function>undefined</function>. + + + whether the value is undefined. + + + + + a #JSCValue + + + + + + Define or modify a property with @property_name in object referenced by @value. When the +property value needs to be getted or set, @getter and @setter callbacks will be called. +When the property is cleared in the #JSCClass context, @destroy_notify is called with +@user_data as parameter. This is equivalent to JavaScript <function>Object.defineProperty()</function> +when used with an accessor descriptor. + +Note that the value returned by @getter must be fully transferred. In case of boxed types, you could use +%G_TYPE_POINTER instead of the actual boxed #GType to ensure that the instance owned by #JSCClass is used. +If you really want to return a new copy of the boxed type, use #JSC_TYPE_VALUE and return a #JSCValue created +with jsc_value_new_object() that receives the copy as instance parameter. + + + + + + + a #JSCValue + + + + the name of the property to define + + + + #JSCValuePropertyFlags + + + + the #GType of the property + + + + a #GCallback to be called to get the property value + + + + a #GCallback to be called to set the property value + + + + user data to pass to @getter and @setter + + + + destroy notifier for @user_data + + + + + + Define or modify a property with @property_name in object referenced by @value. This is equivalent to +JavaScript <function>Object.defineProperty()</function> when used with a data descriptor. + + + + + + + a #JSCValue + + + + the name of the property to define + + + + #JSCValuePropertyFlags + + + + the default property value + + + + + + Try to delete property with @name from @value. This function will return %FALSE if +the property was defined without %JSC_VALUE_PROPERTY_CONFIGURABLE flag. + + + %TRUE if the property was deleted, or %FALSE otherwise. + + + + + a #JSCValue + + + + the property name + + + + + + Get the list of property names of @value. Only properties defined with %JSC_VALUE_PROPERTY_ENUMERABLE +flag will be collected. + + + a %NULL-terminated array of strings containing the + property names, or %NULL if @value doesn't have enumerable properties. Use g_strfreev() to free. + + + + + + + a #JSCValue + + + + + + Get property with @name from @value. + + + the property #JSCValue. + + + + + a #JSCValue + + + + the property name + + + + + + Get property at @index from @value. + + + the property #JSCValue. + + + + + a #JSCValue + + + + the property index + + + + + + Get whether @value has property with @name. + + + %TRUE if @value has a property with @name, or %FALSE otherwise + + + + + a #JSCValue + + + + the property name + + + + + + Invoke method with @name on object referenced by @value, passing the given parameters. If +@first_parameter_type is %G_TYPE_NONE no parameters will be passed to the method. +The object instance will be handled automatically even when the method is a custom one +registered with jsc_class_add_method(), so it should never be passed explicitly as parameter +of this function. + +This function always returns a #JSCValue, in case of void methods a #JSCValue referencing +<function>undefined</function> is returned. + + + a #JSCValue with the return value of the method. + + + + + a #JSCValue + + + + the method name + + + + #GType of first parameter, or %G_TYPE_NONE + + + + value of the first parameter, followed optionally by more type/value pairs, followed by %G_TYPE_NONE + + + + + + Invoke method with @name on object referenced by @value, passing the given @parameters. If +@n_parameters is 0 no parameters will be passed to the method. +The object instance will be handled automatically even when the method is a custom one +registered with jsc_class_add_method(), so it should never be passed explicitly as parameter +of this function. + +This function always returns a #JSCValue, in case of void methods a #JSCValue referencing +<function>undefined</function> is returned. + + + a #JSCValue with the return value of the method. + + + + + a #JSCValue + + + + the method name + + + + the number of parameters + + + + the #JSCValue<!-- -->s to pass as parameters to the method, or %NULL + + + + + + + + Get whether the value referenced by @value is an instance of class @name. + + + whether the value is an object instance of class @name. + + + + + a #JSCValue + + + + a class name + + + + + + Set @property with @name on @value. + + + + + + + a #JSCValue + + + + the property name + + + + the #JSCValue to set + + + + + + Set @property at @index on @value. + + + + + + + a #JSCValue + + + + the property index + + + + the #JSCValue to set + + + + + + Convert @value to a boolean. + + + a #gboolean result of the conversion. + + + + + a #JSCValue + + + + + + Convert @value to a double. + + + a #gdouble result of the conversion. + + + + + a #JSCValue + + + + + + Convert @value to a #gint32. + + + a #gint32 result of the conversion. + + + + + a #JSCValue + + + + + + Convert @value to a string. Use jsc_value_to_string_as_bytes() instead, if you need to +handle strings containing null characters. + + + a null-terminated string result of the conversion. + + + + + a #JSCValue + + + + + + Convert @value to a string and return the results as #GBytes. This is needed +to handle strings with null characters. + + + a #GBytes with the result of the conversion. + + + + + a #JSCValue + + + + + + The #JSCContext in which the value was created. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Flags used when defining properties with jsc_value_object_define_property_data() and +jsc_value_object_define_property_accessor(). + + + the type of the property descriptor may be changed and the + property may be deleted from the corresponding object. + + + the property shows up during enumeration of the properties on + the corresponding object. + + + the value associated with the property may be changed with an + assignment operator. This doesn't have any effect when passed to jsc_value_object_define_property_accessor(). + + + + + + Create a new #JSCVirtualMachine. + + + the newly created #JSCVirtualMachine. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Create a new #JSCWeakValue for the JavaScript value referenced by @value. + + + a new #JSCWeakValue + + + + + a #JSCValue + + + + + + Get a #JSCValue referencing the JavaScript value of @weak_value. + + + a new #JSCValue or %NULL if @weak_value was cleared. + + + + + a #JSCWeakValue + + + + + + The #JSCValue referencing the JavaScript value. + + + + + + + + + + This signal is emitted when the JavaScript value is destroyed. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the major version number of the JavaScriptCore library. +(e.g. in JavaScriptCore version 1.8.3 this is 1.) + +This function is in the library, so it represents the JavaScriptCore library +your code is running against. Contrast with the #JSC_MAJOR_VERSION +macro, which represents the major version of the JavaScriptCore headers you +have included when compiling your code. + + + the major version number of the JavaScriptCore library + + + + + Returns the micro version number of the JavaScriptCore library. +(e.g. in JavaScriptCore version 1.8.3 this is 3.) + +This function is in the library, so it represents the JavaScriptCore library +your code is running against. Contrast with the #JSC_MICRO_VERSION +macro, which represents the micro version of the JavaScriptCore headers you +have included when compiling your code. + + + the micro version number of the JavaScriptCore library + + + + + Returns the minor version number of the JavaScriptCore library. +(e.g. in JavaScriptCore version 1.8.3 this is 8.) + +This function is in the library, so it represents the JavaScriptCore library +your code is running against. Contrast with the #JSC_MINOR_VERSION +macro, which represents the minor version of the JavaScriptCore headers you +have included when compiling your code. + + + the minor version number of the JavaScriptCore library + + + + + Iterates all available options calling @function for each one. Iteration can +stop early if @function returns %FALSE. + + + + + + + a #JSCOptionsFunc callback + + + + callback user data + + + + + + Get @option as a #gboolean value. + + + %TRUE if @value has been set or %FALSE if the option doesn't exist + + + + + the option identifier + + + + return location for the option value + + + + + + Get @option as a #gdouble value. + + + %TRUE if @value has been set or %FALSE if the option doesn't exist + + + + + the option identifier + + + + return location for the option value + + + + + + Get @option as a #gint value. + + + %TRUE if @value has been set or %FALSE if the option doesn't exist + + + + + the option identifier + + + + return location for the option value + + + + + + Create a #GOptionGroup to handle JSCOptions as command line arguments. +The options will be exposed as command line arguments with the form +<emphasis>--jsc-&lt;option&gt;=&lt;value&gt;</emphasis>. +Each entry in the returned #GOptionGroup is configured to apply the +corresponding option during command line parsing. Applications only need to +pass the returned group to g_option_context_add_group(), and the rest will +be taken care for automatically. + + + a #GOptionGroup for the JSCOptions + + + + + Get @option as a range string. The string must be in the +format <emphasis>[!]&lt;low&gt;[:&lt;high&gt;]</emphasis> where low and high are #guint values. +Values between low and high (both included) will be considered in +the range, unless <emphasis>!</emphasis> is used to invert the range. + + + %TRUE if @value has been set or %FALSE if the option doesn't exist + + + + + the option identifier + + + + return location for the option value + + + + + + Get @option as a #gsize value. + + + %TRUE if @value has been set or %FALSE if the option doesn't exist + + + + + the option identifier + + + + return location for the option value + + + + + + Get @option as a string. + + + %TRUE if @value has been set or %FALSE if the option doesn't exist + + + + + the option identifier + + + + return location for the option value + + + + + + Get @option as a #guint value. + + + %TRUE if @value has been set or %FALSE if the option doesn't exist + + + + + the option identifier + + + + return location for the option value + + + + + + Set @option as a #gboolean value. + + + %TRUE if option was correctly set or %FALSE otherwise. + + + + + the option identifier + + + + the value to set + + + + + + Set @option as a #gdouble value. + + + %TRUE if option was correctly set or %FALSE otherwise. + + + + + the option identifier + + + + the value to set + + + + + + Set @option as a #gint value. + + + %TRUE if option was correctly set or %FALSE otherwise. + + + + + the option identifier + + + + the value to set + + + + + + Set @option as a range string. The string must be in the +format <emphasis>[!]&lt;low&gt;[:&lt;high&gt;]</emphasis> where low and high are #guint values. +Values between low and high (both included) will be considered in +the range, unless <emphasis>!</emphasis> is used to invert the range. + + + %TRUE if option was correctly set or %FALSE otherwise. + + + + + the option identifier + + + + the value to set + + + + + + Set @option as a #gsize value. + + + %TRUE if option was correctly set or %FALSE otherwise. + + + + + the option identifier + + + + the value to set + + + + + + Set @option as a string. + + + %TRUE if option was correctly set or %FALSE otherwise. + + + + + the option identifier + + + + the value to set + + + + + + Set @option as a #guint value. + + + %TRUE if option was correctly set or %FALSE otherwise. + + + + + the option identifier + + + + the value to set + + + + + + diff --git a/gir-files/JavaScriptCore-4.0.xsl b/gir-files/JavaScriptCore-4.0.xsl new file mode 100644 index 0000000..5f02d12 --- /dev/null +++ b/gir-files/JavaScriptCore-4.0.xsl @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + + + + Constructor + JSCConstructor + + + + + ClassVariadicFunction + JSCClassVariadicFunction + + + + + + notified + 4 + 5 + + + + + + + + + PropertySetter + JSCPropertySetter + + + + + + + VariadicFunction + JSCVariadicFunction + + + + + + notified + 5 + 6 + + + + + + + + + Setter + JSCSetter + + + + + + + + + + + diff --git a/gir-files/LightDM-1.gir b/gir-files/LightDM-1.gir new file mode 100644 index 0000000..0f037c4 --- /dev/null +++ b/gir-files/LightDM-1.gir @@ -0,0 +1,3307 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #LightDMGreeter is an opaque data structure and can only be accessed +using the provided functions. + + + Create a new greeter. + + + the new #LightDMGreeter + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Starts the authentication procedure for a user. + + + #TRUE if authentication request sent. + + + + + A #LightDMGreeter + + + + A username or #NULL to prompt for a username. + + + + + + Starts the authentication procedure for the guest user. + + + #TRUE if authentication request sent. + + + + + A #LightDMGreeter + + + + + + Starts the authentication procedure for the automatic login user. + + + #TRUE if authentication request sent. + + + + + A #LightDMGreeter + + + + + + Start authentication for a remote session type. + + + #TRUE if authentication request sent. + + + + + A #LightDMGreeter + + + + The name of a remote session + + + + A username of #NULL to prompt for a username. + + + + + + Cancel the current user authentication. + + + #TRUE if cancel request sent. + + + + + A #LightDMGreeter + + + + + + Cancel the automatic login. + + + + + + + A #LightDMGreeter + + + + + + Connects the greeter to the display manager. Will block until connected. + Use lightdm_greeter_connect_to_daemon_sync() instead + + + #TRUE if successfully connected + + + + + The greeter to connect + + + + + + Asynchronously connects the greeter to the display manager. + +When the operation is finished, @callback will be invoked. You can then call lightdm_greeter_connect_to_daemon_finish() to get the result of the operation. + +See lightdm_greeter_connect_to_daemon_sync() for the synchronous version. + + + + + + + The greeter to connect + + + + A #GCancellable or %NULL. + + + + A #GAsyncReadyCallback to call when completed or %NULL. + + + + data to pass to the @callback or %NULL. + + + + + + Finishes an operation started with lightdm_greeter_connect_to_daemon(). + + + #TRUE if successfully connected + + + + + The greeter the the request was done with + + + + A #GAsyncResult. + + + + + + Connects the greeter to the display manager. Will block until connected. + + + #TRUE if successfully connected + + + + + The greeter to connect + + + + + + Ensure that a shared data dir for the given user is available. Both the +greeter user and @username will have write access to that folder. The +intention is that larger pieces of shared data would be stored there (files +that the greeter creates but wants to give to a user -- like camera +photos -- or files that the user creates but wants the greeter to +see -- like contact avatars). + +LightDM will automatically create these if the user actually logs in, so +greeters only need to call this method if they want to store something in +the directory themselves. + + + + + + + A #LightDMGreeter + + + + A username + + + + A #GCancellable or %NULL. + + + + A #GAsyncReadyCallback to call when completed or %NULL. + + + + data to pass to the @callback or %NULL. + + + + + + Function to call from lightdm_greeter_ensure_shared_data_dir callback. + + + The path to the shared directory, free with g_free. + + + + + A #LightDMGreeter + + + + A #GAsyncResult. + + + + + + Ensure that a shared data dir for the given user is available. Both the +greeter user and @username will have write access to that folder. The +intention is that larger pieces of shared data would be stored there (files +that the greeter creates but wants to give to a user -- like camera +photos -- or files that the user creates but wants the greeter to +see -- like contact avatars). + +LightDM will automatically create these if the user actually logs in, so +greeters only need to call this method if they want to store something in +the directory themselves. + + + The path to the shared directory, free with g_free. + + + + + A #LightDMGreeter + + + + A username + + + + + + Get the user that is being authenticated. + + + The username of the authentication user being authenticated or #NULL if no authentication in progress. + + + + + A #LightDMGreeter + + + + + + Check if the guest account should be automatically logged into when the timer expires. + + + #TRUE if the guest account should be automatically logged into. + + + + + A #LightDMGreeter + + + + + + Get the session used to automatically log into when the timer expires. + + + The session name or %NULL if configured to use the default. + + + + + A #LightDMGreeter + + + + + + Get the number of seconds to wait before automatically logging in. + + + The number of seconds to wait before automatically logging in or 0 for no timeout. + + + + + A #LightDMGreeter + + + + + + Get the user account to automatically log into when the timer expires. + + + The user account to automatically log into or %NULL if none configured. + + + + + A #LightDMGreeter + + + + + + Get the default session to use. + + + The session name + + + + + A #LightDMGreeter + + + + + + Check if guest sessions are supported. + + + #TRUE if guest sessions are supported. + + + + + A #LightDMGreeter + + + + + + Check if user accounts should be shown. If this is TRUE then the list of +accounts should be taken from #LightDMUserList and displayed in the greeter +for the user to choose from. Note that this list can be empty and it is +recommended you show a method for the user to enter a username manually. + +If this option is shown the greeter should only allow these users to be +chosen for login unless the manual login hint is set. + + + #TRUE if the available users should not be shown. + + + + + A #LightDMGreeter + + + + + + Get a hint. + + + The value for this hint or #NULL if not set. + + + + + A #LightDMGreeter + + + + The hint name to query. + + + + + + Checks if the greeter is in the process of authenticating. + + + #TRUE if the greeter is authenticating a user. + + + + + A #LightDMGreeter + + + + + + Checks if the greeter has successfully authenticated. + + + #TRUE if the greeter is authenticated for login. + + + + + A #LightDMGreeter + + + + + + Check if the greeter is acting as a lock screen. + + + #TRUE if the greeter was triggered by locking the seat. + + + + + A #LightDMGreeter + + + + + + Check if the guest account should be selected by default. + + + #TRUE if the guest account should be selected by default. + + + + + A #LightDMGreeter + + + + + + Get the user to select by default. + + + A username or %NULL if no particular user should be selected. + + + + + A #LightDMGreeter + + + + + + Check if a manual login option should be shown. If set the GUI +should provide a way for a username to be entered manually. +Without this hint a greeter which is showing a user list can +limit logins to only those users. + + + #TRUE if a manual login option should be shown. + + + + + A #LightDMGreeter + + + + + + Check if a remote login option should be shown. If set the GUI +should provide a way for a user to log into a remote desktop server. + + + #TRUE if a remote login option should be shown. + + + + + A #LightDMGreeter + + + + + + Provide response to a prompt. May be one in a series. + + + #TRUE if response sent. + + + + + A #LightDMGreeter + + + + Response to a prompt + + + + + + Set the language for the currently authenticated user. + + + #TRUE if set language request sent. + + + + + A #LightDMGreeter + + + + The language to use for this user in the form of a locale specification (e.g. "de_DE.UTF-8"). + + + + + + Set whether the greeter will be reset instead of killed after the user logs in. +This must be called before lightdm_greeter_connect is called. + + + + + + + A #LightDMGreeter + + + + Whether the greeter wants to be reset instead of killed after the user logs in + + + + + + Asynchronously start a session for the authenticated user. + +When the operation is finished, @callback will be invoked. You can then call lightdm_greeter_start_session_finish() to get the result of the operation. + +See lightdm_greeter_start_session_sync() for the synchronous version. + + + + + + + A #LightDMGreeter + + + + The session to log into or #NULL to use the default. + + + + A #GCancellable or %NULL. + + + + A #GAsyncReadyCallback to call when completed or %NULL. + + + + data to pass to the @callback or %NULL. + + + + + + Start a session for the authenticated user. + + + TRUE if the session was started. + + + + + A #LightDMGreeter + + + + A #GAsyncResult. + + + + + + Start a session for the authenticated user. + + + TRUE if the session was started. + + + + + A #LightDMGreeter + + + + The session to log into or #NULL to use the default. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The ::authentication-complete signal gets emitted when the greeter +has completed authentication. + +Call lightdm_greeter_get_is_authenticated() to check if the authentication +was successful. + + + + + + The ::timed-login signal gets emitted when the automatic login timer has expired. +The application should then call lightdm_greeter_authenticate_autologin(). + + + + + + The ::idle signal gets emitted when the user has logged in and the +greeter is no longer needed. + +This signal only matters if the greeter has marked itself as +resettable using lightdm_greeter_set_resettable(). + + + + + + The ::reset signal gets emitted when the user is returning to a greeter +that was previously marked idle. + +This signal only matters if the greeter has marked itself as +resettable using lightdm_greeter_set_resettable(). + + + + + + The ::show-message signal gets emitted when the greeter +should show a message to the user. + + + + + + Message text + + + + Message type + + + + + + The ::show-prompt signal gets emitted when the greeter should show a +prompt to the user. The given text should be displayed and an input +field for the user to provide a response. + +Call lightdm_greeter_respond() with the resultant input or +lightdm_greeter_cancel_authentication() to abort the authentication. + + + + + + Prompt text + + + + Prompt type + + + + + + + Class structure for #LightDMGreeter. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Error codes returned by greeter operations. + + error communicating with daemon. + + + failed to connect to the daemon. + + + requested session failed to start. + + + autologin not configured. + + + autologin not configured. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #LightDMLanguage is an opaque data structure and can only be accessed +using the provided functions. + + + Get the code of a language (e.g. "de_DE.UTF-8") + + + The code of the language + + + + + A #LightDMLanguage + + + + + + Get the name of a language. + + + The name of the language + + + + + A #LightDMLanguage + + + + + + Get the territory the language is used in. + + + The territory the language is used in. + + + + + A #LightDMLanguage + + + + + + Check if a language code matches this language. + + + #TRUE if the code matches this language. + + + + + A #LightDMLanguage + + + + A language code + + + + + + + + + + + + + + + + + + + Class structure for #LightDMLanguage. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #LightDMLayout is an opaque data structure and can only be accessed +using the provided functions. + + + Get the long description of a layout. + + + A long description of the layout + + + + + A #LightDMLayout + + + + + + Get the name of a layout. + + + The name of the layout + + + + + A #LightDMLayout + + + + + + Get the short description of a layout. + + + A short description of the layout + + + + + A #LightDMLayout + + + + + + + + + + + + + + + + + + + Class structure for #LightDMLayout. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Informational message. + + + Error message. + + + + Prompt types the client is required to display. + + prompt is a question. The information can be shown as it is entered. + + + prompt is for secret information. The entered information should be obscured so it can't be publically visible. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #LightDMSession is an opaque data structure and can only be accessed +using the provided functions. + + + Get the comment for a session + + + The session comment + + + + + A #LightDMSession + + + + + + Get the key for a session + + + The session key + + + + + A #LightDMSession + + + + + + Get the name for a session + + + The session name + + + + + A #LightDMSession + + + + + + Get the type a session + + + The session type, e.g. x or mir + + + + + A #LightDMSession + + + + + + + + + + + + + + + + + + + Class structure for #LightDMSession. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #LightDMUser is an opaque data structure and can only be accessed +using the provided functions. + + + + + + + + + + + + + + Get the background file path for a user. + + + The background file path for the given user or #NULL if no path + + + + + A #LightDMUser + + + + + + Get the display name of a user. + + + The display name of the given user + + + + + A #LightDMUser + + + + + + Check if a user has waiting messages. + + + #TRUE if the user has waiting messages. + + + + + A #LightDMUser + + + + + + Get the home directory for a user. + + + The users home directory + + + + + A #LightDMUser + + + + + + Get the image URI for a user. + + + The image URI for the given user or #NULL if no URI + + + + + A #LightDMUser + + + + + + Get if the user is locked. + + + %TRUE if the user is locked + + + + + A #LightDMUser + + + + + + Get the language for a user. + + + The language in the form of a local specification (e.g. "de_DE.UTF-8") for the given user or #NULL if using the system default locale. + + + + + A #LightDMUser + + + + + + Get the keyboard layout for a user. + + + The keyboard layout for the given user or #NULL if using system defaults. Copy the value if you want to use it long term. + + + + + A #LightDMUser + + + + + + Get the configured keyboard layouts for a user. + + + A NULL-terminated array of keyboard layouts for the given user. Copy the values if you want to use them long term. + + + + + + + A #LightDMUser + + + + + + Check if a user is logged in. + + + #TRUE if the user is currently logged in. + + + + + A #LightDMUser + + + + + + Get the name of a user. + + + The name of the given user + + + + + A #LightDMUser + + + + + + Get the real name of a user. + + + The real name of the given user + + + + + A #LightDMUser + + + + + + Get the session for a user. + + + The session for the given user or #NULL if using system defaults. + + + + + A #LightDMUser + + + + + + Get the uid of a user. + + + The uid of the given user + + + + + A #LightDMUser + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The ::changed signal gets emitted this user account is modified. + + + + + + + Class structure for #LightDMUser. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + #LightDMUserList is an opaque data structure and can only be accessed +using the provided functions. + + + Get the user list. + + + the #LightDMUserList + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The number of users able to log in + + + + + a #LightDMUserList + + + + + + Get information about a given user or #NULL if this user doesn't exist. + + + A #LightDMUser entry for the given user. + + + + + A #LightDMUserList + + + + Name of user to get. + + + + + + Get a list of users to present to the user. This list may be a subset of the +available users and may be empty depending on the server configuration. + + + A list of #LightDMUser that should be presented to the user. + + + + + + + A #LightDMUserList + + + + + + + + + + + + + + + The ::user-added signal gets emitted when a user account is created. + + + + + + The #LightDMUser that has been added. + + + + + + The ::user-changed signal gets emitted when a user account is modified. + + + + + + The #LightDMUser that has been changed. + + + + + + The ::user-removed signal gets emitted when a user account is removed. + + + + + + The #LightDMUser that has been removed. + + + + + + + Class structure for #LightDMUserList. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Checks if is authorized to do a system hibernate. + + + #TRUE if can hibernate the system + + + + + Checks if is authorized to do a system restart. + + + #TRUE if can restart the system + + + + + Checks if is authorized to do a system shutdown. + + + #TRUE if can shutdown the system + + + + + Checks if authorized to do a system suspend. + + + #TRUE if can suspend the system + + + + + + + The name of the host we are running on. + + + + + Get the current language. + + + The current language or #NULL if no language. + + + + + Get a list of languages to present to the user. + + + A list of #LightDMLanguage that should be presented to the user. + + + + + + + Get the current keyboard layout. + + + The currently active layout for this user. + + + + + Get a list of keyboard layouts to present to the user. + + + A list of #LightDMLayout that should be presented to the user. + + + + + + + Get a system message that should be presented to the user. +e.g. "Welcome to Yoyodyne" + + + a string (the contents of /etc/motd) or %NULL if not set. + + + + + Get a word describing the OS, suitable for checking which OS the greeter is running on. +e.g. "ubuntu" + + + a string (ID variable from /etc/os-release) or %NULL if not set. + + + + + Get a line of text describing the OS without version information, suitable for presentation to the user. +e.g. "Ubuntu" + + + a string (NAME variable from /etc/os-release) or %NULL if not set. + + + + + Get a line of text describing the OS, suitable for presentation to the user. +e.g. "Ubuntu 16.04.1 LTS" + + + a string (PRETTY_NAME variable from /etc/os-release) or %NULL if not set. + + + + + Get a line of text describing the OS version, suitable for presentation to the user. +e.g. "16.04.1 LTS (Xenial Xapus)" + + + a string (VERSION variable from /etc/os-release) or %NULL if not set. + + + + + Get a word descibing the OS version, suitable for checking which version of the OS this greeter is running on. +e.g. "16.04" + + + a string (VERSION_ID variable from /etc/os-release) or %NULL if not set. + + + + + Get the available remote sessions. + + + A list of #LightDMSession + + + + + + + Get the available sessions. + + + A list of #LightDMSession + + + + + + + + + + + + Triggers a system hibernate. + + + #TRUE if hibernate initiated. + + + + + Triggers a system restart. + + + #TRUE if restart initiated. + + + + + Set the layout for this session. + + + + + + + The layout to use + + + + + + Triggers a system shutdown. + + + #TRUE if shutdown initiated. + + + + + Triggers a system suspend. + + + #TRUE if suspend initiated. + + + + + diff --git a/gir-files/Pango-1.0.gir b/gir-files/Pango-1.0.gir new file mode 100644 index 0000000..a338d53 --- /dev/null +++ b/gir-files/Pango-1.0.gir @@ -0,0 +1,12330 @@ + + + + + + + + + + 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. + + + + + The #PangoLayoutRun structure represents a single run within +a #PangoLayoutLine; it is simply an alternate name for +#PangoGlyphItem. +See the #PangoGlyphItem docs for details on the fields. + + + + + Whether the segment should be shifted to center around the baseline. +Used in vertical writing directions mostly. + + + + + This flag is used to mark runs that hold ellipsized text, +in an ellipsized layout. + + + + + This value can be used to set the start_index member of a #PangoAttribute +such that the attribute covers from the beginning of the text. + + + + + A #PangoAlignment describes how to align the lines of a #PangoLayout within the +available space. If the #PangoLayout is set to justify +using pango_layout_set_justify(), this only has effect for partial lines. + + 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. + + + the engine for doing rendering-system-dependent processing. + + + + the engine for doing rendering-system-independent processing. + + + + the font for this segment. + + + + the bidirectional level for this segment. + + + + the glyph orientation for this segment (A #PangoGravity). + + + + boolean flags for this segment (currently only one) (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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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 featues, as a string in CSS syntax + + + + Create a new font features tag attribute. + + + the newly allocated #PangoAttribute, + which should be freed with pango_attribute_destroy(). + + + + + a string with OpenType font features, in CSS syntax + + + + + + + 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 + + + + + The #PangoAttrIterator structure is used to represent an +iterator through a #PangoAttrList. A new iterator is created +with pango_attr_list_get_iterator(). Once the iterator +is created, it can be advanced through the style changes +in the text using pango_attr_iterator_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 + pango_attr_iterator_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 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 + pango_font_description_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: + <literal>pango_font_description_set_family (desc, pango_font_description_get_family (desc))</literal>. + + + + if non-%NULL, location to store language tag for item, or %NULL + if none is found. + + + + if non-%NULL, + 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 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 pango_attribute_destroy(). + + + + + language tag + + + + + + + The #PangoAttrList structure represents a list of attributes +that apply to a section of text. The attributes are, in general, +allowed to overlap in an arbitrary fashion, however, if the +attributes are manipulated only through pango_attr_list_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 pango_attr_list_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 pango_attr_list_insert() for +creating a attribute list in order (potentially much slower +for large lists). However, pango_attr_list_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. Ownership of this + value is assumed by the list. + + + + + + Copy @list and return an identical new list. + + + the newly allocated #PangoAttrList, with a + reference count of one, which should + be freed with pango_attr_list_unref(). + Returns %NULL if @list was %NULL. + + + + + a #PangoAttrList, may be %NULL + + + + + + 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 + + + + + + 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 pango_attr_iterator_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. Ownership of this + value is assumed by the list. + + + + + + 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. Ownership of this + value is assumed by the list. + + + + + + Increase the reference count of the given attribute list by one. + + + The attribute list passed in + + + + + a #PangoAttrList, may be %NULL + + + + + + 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 pango_attr_list_change() with a copy +of each attribute in @other in sequence (offset in position by @pos). + +This operation proves useful for, for instance, inserting +a pre-edit string in the middle of an edit buffer. + + + + + + + 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) + + + + + + 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, may be %NULL + + + + + + + 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 pango_attr_shape_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 pango_attribute_destroy(). + + + + + ink rectangle to assign to each character + + + + logical rectangle to assign to each character + + + + + + Like pango_attr_shape_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 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, or %NULL + + + + + + + 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 uni (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 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 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 pango_attr_type_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 (#PangoAttrLanguage) + + + font family name list (#PangoAttrString) + + + font slant style (#PangoAttrInt) + + + font weight (#PangoAttrInt) + + + font variant (normal or small caps) (#PangoAttrInt) + + + font stretch (#PangoAttrInt) + + + font size in points scaled by %PANGO_SCALE (#PangoAttrInt) + + + font description (#PangoAttrFontDesc) + + + foreground color (#PangoAttrColor) + + + background color (#PangoAttrColor) + + + whether the text has an underline (#PangoAttrInt) + + + whether the text is struck-through (#PangoAttrInt) + + + baseline displacement (#PangoAttrInt) + + + shape (#PangoAttrShape) + + + font size scale factor (#PangoAttrFloat) + + + whether fallback is enabled (#PangoAttrInt) + + + letter spacing (#PangoAttrInt) + + + underline color (#PangoAttrColor) + + + strikethrough color (#PangoAttrColor) + + + font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt) + + + base text gravity (#PangoAttrInt) + + + gravity hint (#PangoAttrInt) + + + OpenType font features (#PangoAttrString). Since 1.38 + + + foreground alpha (#PangoAttrInt). Since 1.38 + + + background alpha (#PangoAttrInt). Since 1.38 + + + Fetches the attribute type name passed in when registering the type using +pango_attr_type_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 pango_attr_type_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 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. + + + + Make a copy of an attribute. + + + the newly allocated #PangoAttribute, + which should be freed with 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 + + + + + + + The #PangoBidiType type represents the bidirectional character +type of a Unicode character as specified by the +<ulink url="http://www.unicode.org/reports/tr9/">Unicode bidirectional algorithm</ulink>. + + 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 + + + Determines the normative bidirectional character type of a +character, as specified in the Unicode Character Database. + +A simplified version of this function is available as +pango_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, which should be freed with +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 pango_color_free(), or %NULL if + @src was %NULL. + + + + + color to copy, may be %NULL + + + + + + Frees a color allocated by pango_color_copy(). + + + + + + + an allocated #PangoColor, may be %NULL + + + + + + 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 <ulink url="http://dev.w3.org/csswg/css-color/#named-colors">specification</ulink>), or it can be a hexadecimal +value in the +form '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb' or '&num;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 '&num;fff' '&num;ffffff' '&num;fffffffff' and '&num;ffffffffffff') + + + %TRUE if parsing of the specifier succeeded, + otherwise false. + + + + + a #PangoColor structure in which to store the + result, or %NULL + + + + a string specifying the new color + + + + + + Returns a textual specification of @color in the hexadecimal form +<literal>&num;rrrrggggbbbb</literal>, where <literal>r</literal>, +<literal>g</literal> and <literal>b</literal> 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 + + + + + + + The #PangoContext structure stores global information +used to control the itemization process. + + + Creates a new #PangoContext initialized to default values. + +This function is not particularly useful as it should always +be followed by a pango_context_set_font_map() call, and the +function pango_font_map_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, +gdk_pango_context_get_for_screen(), and +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 +pango_context_set_base_dir(). + + + the base direction for the context. + + + + + a #PangoContext + + + + + + Retrieves the base gravity for the context. See +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 +pango_context_get_base_gravity(), except for when the base gravity +is %PANGO_GRAVITY_AUTO for which 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 +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 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 pango_itemize(), and the family name may be a comma separated +list of figures. 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 pango_font_metrics_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 pango_language_get_default()) + will be returned. + + + + + + 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 pango_context_get_gravity() +is set %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 +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.) + + + + + + + + + + The #PangoCoverage structure represents a map from Unicode characters +to #PangoCoverageLevel. It is an opaque structure with no public fields. + + + Copy an existing #PangoCoverage. (This function may now be unnecessary +since we refcount the structure. File a bug if you use it.) + + + the newly allocated #PangoCoverage, + with a reference count of one, which should be freed + with 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. + + + + + + + a #PangoCoverage + + + + another #PangoCoverage + + + + + + Increase the reference count on the #PangoCoverage by one + + + @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 + + + + + + + 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. + + + + + + + a #PangoCoverage + + + + + + Convert data generated from pango_coverage_to_bytes() back +to a #PangoCoverage + + + a newly allocated + #PangoCoverage, or %NULL if the data was invalid. + + + + + binary data + representing a #PangoCoverage + + + + + + the size of @bytes in bytes + + + + + + Create a new #PangoCoverage + + + the newly allocated #PangoCoverage, + initialized to %PANGO_COVERAGE_NONE + with a reference count of one, which + should be freed with pango_coverage_unref(). + + + + + + Used to indicate how well a font can represent a particular Unicode +character point for a particular script. + + 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. + + + + The #PangoDirection type 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 pango_unichar_direction() +and pango_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 pango_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. + + 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 + + + + A string constant defining the engine type for language engines. +These engines derive from #PangoEngineLang. + + + + + A string constant defining the engine type for shaping engines. +These engines derive from #PangoEngineShape. + + + + + The #PangoEllipsizeMode type describes what sort of (if any) +ellipsization should be applied to a line of 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 + + + + #PangoEngine is the base class for all types of language and +script specific engines. It has no functionality by itself. + + + + + + + Class structure for #PangoEngine + + + + + + + The #PangoEngineInfo structure contains information about a particular +engine. It contains the following fields: + + + a unique string ID for the engine. + + + + a string identifying the engine type. + + + + a string identifying the render type. + + + + array of scripts this engine supports. + + + + number of items in @scripts. + + + + + The #PangoEngineLang class is implemented by engines that +customize the rendering-system independent part of the +Pango pipeline for a particular script or language. For +instance, a custom #PangoEngineLang could be provided for +Thai to implement the dictionary-based word boundary +lookups needed for that language. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Class structure for #PangoEngineLang + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #PangoEngineScriptInfo structure contains +information about how the shaper covers a particular script. + + + a #PangoScript. The value %PANGO_SCRIPT_COMMON has +the special meaning here of "all scripts" + + + + a semicolon separated list of languages that this +engine handles for this script. This may be empty, +in which case the engine is saying that it is a +fallback choice for all languages for this range, +but should not be used if another engine +indicates that it is specific for the language for +a given code point. An entry in this list of "*" +indicates that this engine is specific to all +languages for this range. + + + + + The #PangoEngineShape class is implemented by engines that +customize the rendering-system dependent part of the +Pango pipeline for a particular script or language. +A #PangoEngineShape implementation is then specific to both +a particular rendering system or group of rendering systems +and to a particular script. For instance, there is one +#PangoEngineShape implementation to handle shaping Arabic +for Fontconfig-based backends. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Class structure for #PangoEngineShape + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #PangoFont structure is used to represent +a font in a rendering-system-independent matter. +To create an implementation of a #PangoFont, +the rendering-system specific code should allocate +a larger structure that contains a nested +#PangoFont, fill in the <structfield>klass</structfield> member of +the nested #PangoFont with a pointer to +a appropriate #PangoFontClass, then call +pango_font_init() on the structure. + +The #PangoFont structure contains one member +which the implementation fills in. + + + Frees an array of font descriptions. + + + + + + + a pointer +to an array of #PangoFontDescription, may be %NULL + + + + + + number of font descriptions in @descs + + + + + + Returns a description of the font, with font size set in points. +Use pango_font_describe_with_absolute_size() if you want the font +size in device units. + + + a newly-allocated #PangoFontDescription object. + + + + + a #PangoFont + + + + + + + + + + + + + + + + + Finds the best matching shaper for a font for a particular +language tag and character point. + + + the best matching shaper. + + + + + a #PangoFont + + + + the language tag + + + + a Unicode character. + + + + + + Computes the coverage map for a given font and language tag. + + + a newly-allocated #PangoCoverage + object. + + + + + a #PangoFont + + + + the language tag + + + + + + Gets the font map for which the font was created. + +Note that the font maintains a <firstterm>weak</firstterm> 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, or %NULL if @font is %NULL. + + + + + a #PangoFont, or %NULL + + + + + + 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 or %NULL to indicate that the result is not needed. + + + + rectangle used to store the logical extents of + the glyph or %NULL to indicate that the result is not needed. + + + + + + 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 pango_font_metrics_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 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 pango_font_describe() if you want the font +size in points. + + + a newly-allocated #PangoFontDescription object. + + + + + a #PangoFont + + + + + + Finds the best matching shaper for a font for a particular +language tag and character point. + + + the best matching shaper. + + + + + a #PangoFont + + + + the language tag + + + + a Unicode character. + + + + + + Computes the coverage map for a given font and language tag. + + + a newly-allocated #PangoCoverage + object. + + + + + a #PangoFont + + + + the language tag + + + + + + Gets the font map for which the font was created. + +Note that the font maintains a <firstterm>weak</firstterm> 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, or %NULL if @font is %NULL. + + + + + a #PangoFont, or %NULL + + + + + + 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 or %NULL to indicate that the result is not needed. + + + + rectangle used to store the logical extents of + the glyph or %NULL to indicate that the result is not needed. + + + + + + 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 pango_font_metrics_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. + + + + + + + + + + + + + + + + + + a newly-allocated #PangoFontDescription object. + + + + + a #PangoFont + + + + + + + + + + a newly-allocated #PangoCoverage + object. + + + + + a #PangoFont + + + + the language tag + + + + + + + + + + the best matching shaper. + + + + + a #PangoFont + + + + the language tag + + + + a Unicode character. + + + + + + + + + + + + + + a #PangoFont + + + + the glyph index + + + + rectangle used to store the extents of the glyph + as drawn or %NULL to indicate that the result is not needed. + + + + rectangle used to store the logical extents of + the glyph or %NULL to indicate that the result is not needed. + + + + + + + + + + a #PangoFontMetrics object. The caller must call pango_font_metrics_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, or %NULL if @font is %NULL. + + + + + a #PangoFont, or %NULL + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #PangoFontDescription structure represents the description +of an ideal font. These 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 pango_font_description_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 + pango_font_description_free(), or %NULL if @desc was + %NULL. + + + + + a #PangoFontDescription, may be %NULL + + + + + + Like pango_font_description_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 + pango_font_description_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 + + + + + + Gets the family name field of a font description. See +pango_font_description_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 gravity field of a font description. See +pango_font_description_set_gravity(). + + + the gravity field for the font description. Use + pango_font_description_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 pango_font_description_set_size(). + + + the size field for the font description in points or device units. + You must call pango_font_description_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 pango_font_description_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 pango_font_description_set_size() and pango_font_description_set_absolute_size(). + + + whether the size for the font description is in + points or device units. Use pango_font_description_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 pango_font_description_set_stretch(). + + + the stretch field for the font description. Use + pango_font_description_get_set_fields() to find out if + the field was explicitly set or not. + + + + + a #PangoFontDescription. + + + + + + Gets the style field of a #PangoFontDescription. See +pango_font_description_set_style(). + + + the style field for the font description. + Use pango_font_description_get_set_fields() to find out if + the field was explicitly set or not. + + + + + a #PangoFontDescription + + + + + + Gets the variant field of a #PangoFontDescription. See +pango_font_description_set_variant(). + + + the variant field for the font description. Use + pango_font_description_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 +pango_font_description_set_variations(). + + + the varitions 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 +pango_font_description_set_weight(). + + + the weight field for the font description. Use + pango_font_description_get_set_fields() to find out if + the field was explicitly set or not. + + + + + a #PangoFontDescription + + + + + + Computes a hash of a #PangoFontDescription structure 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. + + + + + + Like pango_font_description_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 pango_font_description_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 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. + + + + + + Like pango_font_description_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 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 pango_font_description_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 pango_font_description_set_absolute_size() if you need + a particular size in device units. + + + + + + Sets the stretch field of a font description. The 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 +#PangoStyle 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 #PangoVariant +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 or freetype have API for this. + + + + + + + a #PangoFontDescription. + + + + + + + + + Like pango_font_description_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 + + + + + + + + + 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 #PangoWeight 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 +pango_font_description_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 +pango_font_description_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 in the +form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", 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. 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 new #PangoFontDescription. + + + + + string representation of a font description. + + + + + + + The #PangoFontFace structure is used to represent a group of fonts with +the same family, slant, weight, width, but varying sizes. + + + Returns the family, style, variant, weight and stretch of +a #PangoFontFace. The size field of the resulting font description +will be unset. + + + a newly-created #PangoFontDescription structure + holding the description of the face. Use pango_font_description_free() + to free the result. + + + + + a #PangoFontFace + + + + + + Gets a name representing the style of this face among the +different faces in the #PangoFontFamily for the face. This +name is unique among all faces in the family and is suitable +for displaying to users. + + + the face name for the face. This string is + owned by the face object and must not be modified or freed. + + + + + a #PangoFontFace. + + + + + + Returns whether a #PangoFontFace is synthesized by the underlying +font rendering engine from another face, perhaps by shearing, emboldening, +or lightening it. + + + 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 the family, style, variant, weight and stretch of +a #PangoFontFace. The size field of the resulting font description +will be unset. + + + a newly-created #PangoFontDescription structure + holding the description of the face. Use pango_font_description_free() + to free the result. + + + + + a #PangoFontFace + + + + + + Gets a name representing the style of this face among the +different faces in the #PangoFontFamily for the face. This +name is unique among all faces in the family and is suitable +for displaying to users. + + + the face name for the face. This string is + owned by the face object and must not be modified or freed. + + + + + a #PangoFontFace. + + + + + + Returns whether a #PangoFontFace is synthesized by the underlying +font rendering engine from another face, perhaps by shearing, emboldening, +or lightening it. + + + 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 pango_font_description_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 structure is used to represent a family of related +font faces. The faces in a family share a common design, but differ in +slant, weight, width and other aspects. + + + 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 +pango_font_metrics_get_approximate_digit_width(), since the results +of pango_font_metrics_get_approximate_char_width() may be affected +by double-width characters. + + + %TRUE if the family is monospace. + + + + + 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. + + + + + + + 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 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 +pango_font_metrics_get_approximate_digit_width(), since the results +of pango_font_metrics_get_approximate_char_width() may be affected +by double-width characters. + + + %TRUE if the family is monospace. + + + + + 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. + + + + + + + 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. + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #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. To +create an implementation of a #PangoFontMap, the rendering-system +specific code should allocate a larger structure that contains a nested +#PangoFontMap, fill in the <structfield>klass</structfield> member of the nested #PangoFontMap with a +pointer to a appropriate #PangoFontMapClass, then call +pango_font_map_init() on the structure. + +The #PangoFontMap structure contains one member which the implementation +fills in. + + + Forces a change in the context, 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 context +and such data is changed. + + + + + + + a #PangoFontMap + + + + + + 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. + + + + + + + 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 + + + + + + Forces a change in the context, 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 context +and such data is changed. + + + + + + + a #PangoFontMap + + + + + + Creates a #PangoContext connected to @fontmap. This is equivalent +to pango_context_new() followed by 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, +gdk_pango_context_get_for_screen(), and +gtk_widget_get_pango_context(). Use those instead. + + + the newly allocated #PangoContext, + which should be freed with g_object_unref(). + + + + + a #PangoFontMap + + + + + + 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 + + + + + + Returns the render ID for shape engines for this fontmap. +See the <structfield>render_type</structfield> field of +#PangoEngineInfo. + + + the ID string for shape engines for + this fontmap. Owned by Pango, should not be modified + or freed. + + + + + a #PangoFontMap + + + + + + List all families for a fontmap. + + + + + + + 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 + + + + + + + + + + The #PangoFontMapClass structure holds the virtual functions for +a particular #PangoFontMap implementation. + + + parent #GObjectClass. + + + + + + + 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 #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 + + + + + + + + + + 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. + + + + + + + The current serial number of @fontmap. + + + + + a #PangoFontMap + + + + + + + + + + + + + + a #PangoFontMap + + + + + + + + + + + + + + + + + + + + + + + + The bits in a #PangoFontMask correspond to fields in a +#PangoFontDescription that have been set. + + 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 (Since: 1.16.) + + + OpenType font variations are specified (Since: 1.42) + + + + A #PangoFontMetrics structure holds the overall metric information +for a font (possibly 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #PangoFontMetrics structure. This is only for +internal use by Pango backends and there is no public way +to set the fields of the structure. + + + a newly-created #PangoFontMetrics structure + with a reference count of 1. + + + + + 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 suggested position to draw the strikethrough. +The value returned is the distance <emphasis>above</emphasis> 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 <emphasis>above</emphasis> 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 + + + + + + + A #PangoFontset represents a set of #PangoFont to use +when rendering text. It 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 the +Unicode character @wc. + + + a #PangoFont. The caller must call + g_object_unref when finished with the font. + + + + + a #PangoFontset + + + + a Unicode character + + + + + + + + + + + + + + + + + Get overall metric information for the fonts in the fontset. + + + a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() + when finished using the 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 the +Unicode character @wc. + + + a #PangoFont. The caller must call + g_object_unref when finished with the font. + + + + + a #PangoFontset + + + + a Unicode character + + + + + + Get overall metric information for the fonts in the fontset. + + + a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() + when finished using the object. + + + + + a #PangoFontset + + + + + + + + + + The #PangoFontsetClass structure holds the virtual functions for +a particular #PangoFontset implementation. + + + parent #GObjectClass. + + + + + + + a #PangoFont. The caller must call + g_object_unref when finished with the font. + + + + + a #PangoFontset + + + + a Unicode character + + + + + + + + + + a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() + when finished using the object. + + + + + a #PangoFontset + + + + + + + + + + + + + + + + + + + + + + + + + + + a #PangoFontset + + + + Callback function + + + + data to pass to the callback function + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A callback function used by pango_fontset_foreach() when enumerating +the fonts in a fontset. + + + 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 in terms of an array of fonts, +which the creator provides when constructing the +#PangoFontsetSimple. + + + Creates a new #PangoFontsetSimple for the given language. + + + the newly allocated #PangoFontsetSimple, which should + be freed with g_object_unref(). + + + + + a #PangoLanguage tag + + + + + + Adds a font to the fontset. + + + + + + + a #PangoFontsetSimple. + + + + a #PangoFont. + + + + + + Returns the number of fonts in the fontset. + + + the size of @fontset. + + + + + a #PangoFontsetSimple. + + + + + + + + + + The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a + special meaning, which is a zero-width empty glyph. This is useful for +example in shaper modules, to use as the glyph for various zero-width +Unicode characters (those passing pango_is_zero_width()). + + + + + The %PANGO_GLYPH_INVALID_INPUT macro represents a #PangoGlyph value that has a +special meaning of 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 +on. + + + + + The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to +a #gunichar value of a valid Unicode character, to produce a #PangoGlyph +value, representing an unknown-character glyph for the respective #gunichar. + + + + + The #PangoGlyphGeometry structure contains width and positioning +information for a single glyph. + + + the logical width to use for the the character. + + + + horizontal offset from nominal character position. + + + + vertical offset from nominal character position. + + + + + The #PangoGlyphInfo structure represents a single glyph together with +positioning information and visual attributes. +It contains the following fields. + + + 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 text corresponding to an item. +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. + + + + 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 (pango_attr_list_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 pango_glyph_item_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, which should + be freed with pango_glyph_item_free(), or %NULL + if @orig was %NULL. + + + + + a #PangoGlyphItem, may be %NULL + + + + + + Frees a #PangoGlyphItem and resources to which it points. + + + + + + + a #PangoGlyphItem, may be %NULL + + + + + + Given a #PangoGlyphItem and the corresponding +text, determine the screen 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 pango_glyph_string_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 <firstterm>forward direction</firstterm> 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 <literal>@glyph_item->item->analysis.level</literal> 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 of +pango_glyph_item_iter_init_start() and +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: +<programlisting> +PangoGlyphItemIter cluster_iter; +gboolean have_cluster; + +for (have_cluster = pango_glyph_item_iter_init_start (&amp;cluster_iter, + glyph_item, text); + have_cluster; + have_cluster = pango_glyph_item_iter_next_cluster (&amp;cluster_iter)) +{ + ... +} +</programlisting> + +Note that @text is the start of the text for layout, which is then +indexed by <literal>@glyph_item->item->offset</literal> 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, which should + be freed with pango_glyph_item_iter_free(), or %NULL + if @orig was %NULL. + + + + + a #PangoGlyphItemIter, may be %NULL + + + + + + Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy(). + + + + + + + a #PangoGlyphItemIter, may be %NULL + + + + + + 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 + + + + + + + The #PangoGlyphString structure 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 the glyphs in this glyph string. + + + + array of glyph information + for the glyph string. + + + + + + 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 pango_glyph_string_free(). + + + + + Copy a glyph string and associated storage. + + + the newly allocated #PangoGlyphString, + which should be freed with pango_glyph_string_free(), + or %NULL if @string was %NULL. + + + + + a #PangoGlyphString, may be %NULL + + + + + + Compute the logical and ink extents of a glyph string. See the documentation +for pango_font_get_glyph_extents() for details about the interpretation +of the rectangles. + + + + + + + a #PangoGlyphString + + + + a #PangoFont + + + + rectangle used to store the extents of the glyph string + as drawn or %NULL to indicate that the result is not needed. + + + + rectangle used to store the logical extents of the + glyph string or %NULL to indicate that the result is not needed. + + + + + + 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 or + %NULL to indicate that the result is not needed. + + + + rectangle used to + store the logical extents of the glyph string range or + %NULL to indicate that the result is not needed. + + + + + + Free a glyph string and associated storage. + + + + + + + a #PangoGlyphString, may be %NULL + + + + + + Given a #PangoGlyphString resulting from pango_shape() and the corresponding +text, determine the screen 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 pango_glyph_item_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 as can also be computed +using pango_glyph_string_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. (X position +is measured from the left edge of the run). Character positions +are computed by dividing up each cluster into equal portions. + + + + + + + the glyphs return from pango_shape() + + + + the text for the run + + + + the number of bytes (not characters) in @text. + + + + the analysis information return from pango_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 + + + + + + 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 pango_shape() + + + + the text for the run + + + + the number of bytes (not characters) in text. + + + + the analysis information return from pango_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. + + + + + + + The PangoGlyphVisAttr is used to communicate information between +the shaping phase and the rendering phase. More attributes may be +added in the future. + + + set for the first logical glyph in each cluster. (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.) + + + + + The #PangoGravity type 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 PangoMatrix, +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 +pango_context_set_base_gravity() and can only be returned by +pango_context_get_base_gravity(). + +See also: #PangoGravityHint + + Glyphs stand upright (default) + + + Glyphs are rotated 90 degrees clockwise + + + Glyphs are upside-down + + + Glyphs are rotated 90 degrees counter-clockwise + + + 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 + + + + + + Based on the script, base gravity, and hint, returns actual gravity +to use in laying out a single #PangoItem. + +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 + + + + + + Based on the script, East Asian width, base gravity, and hint, +returns actual gravity to use in laying out a single character +or #PangoItem. + +This function is similar to 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 <emphasis>upright</emphasis>, 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. +@gravity should not be %PANGO_GRAVITY_AUTO. + +Note that pango_matrix_rotate() takes angle in degrees, not radians. +So, to call 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 + + + + + + + The #PangoGravityHint defines how horizontal scripts should behave in a +vertical context. That is, English excerpt in a vertical paragraph for +example. + +See #PangoGravity. + + 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 #PangoIncludedModule structure for a statically linked module +contains the functions that would otherwise be loaded from a dynamically +loaded module. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #PangoItem structure stores information about a segment of text. + + + 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 pango_item_free(). + + + + + Copy an existing #PangoItem structure. + + + the newly allocated #PangoItem, which + should be freed with pango_item_free(), or %NULL if + @item was %NULL. + + + + + a #PangoItem, may be %NULL + + + + + + Free a #PangoItem and all associated memory. + + + + + + + a #PangoItem, may be %NULL + + + + + + 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 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 + + + + + + + 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 +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: +<informalexample><programlisting> +pango_language_get_sample_string (pango_language_from_string ("xx")) +</programlisting></informalexample> + + + the sample string. This value is owned by Pango + and should not be freed. + + + + + a #PangoLanguage, or %NULL + + + + + + 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 pango_language_includes_script() function uses this function +internally. + + + 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). The returned array is owned by Pango and should not be +modified or freed. + + + + + + + a #PangoLanguage, or %NULL + + + + location to return number of scripts, + or %NULL + + + + + + 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 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, or %NULL + + + + 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 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 pango_language_from_string() + + + + + + Gets the RFC-3066 format string representing the given language tag. + + + a string representing the language tag. This is owned by + Pango and should not be freed. + + + + + a language tag. + + + + + + Take a RFC-3066 format language tag as a string and convert it to a +#PangoLanguage pointer that 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 pango_language_get_default() if you want to get the #PangoLanguage for +the current locale of the process. + + + an opaque pointer to a + #PangoLanguage structure, or %NULL if @language was + %NULL. The returned pointer will be valid forever + after, and should not be freed. + + + + + a string representing a language tag, or %NULL + + + + + + Returns the #PangoLanguage for the current locale of the process. +Note that this can change over the life of an application. + +On Unix systems, this is the return value is derived from +<literal>setlocale(LC_CTYPE, NULL)</literal>, 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 <literal>setlocale(LC_ALL, "");</literal> +for the user settings to take effect. Gtk+ does this in its initialization +functions automatically (by calling gtk_set_locale()). +See <literal>man setlocale</literal> for more details. + + + the default language as a + #PangoLanguage, must not be freed. + + + + + + The #PangoLayout structure represents an entire paragraph +of text. It 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 also a number of parameters to adjust the formatting +of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>. +It is possible, as well, to ignore the 2-D setup, and simply +treat the results of a #PangoLayout as a list of lines. + +<figure id="parameters"> +<title>Adjustable parameters for a PangoLayout</title> +<graphic fileref="layout.gif" format="GIF"></graphic> +</figure> + +The #PangoLayout structure is opaque, and has no user-visible +fields. + + + Create a new #PangoLayout object with attributes initialized to +default values for a particular #PangoContext. + + + the newly allocated #PangoLayout, with a reference + count of one, which should be freed with + g_object_unref(). + + + + + a #PangoContext + + + + + + 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 + + + + + + Does a deep copy-by-value of the @src layout. The attribute list, +tab array, and text from the original layout are all copied by +value. + + + the newly allocated #PangoLayout, + with a reference count of one, which should be freed + with g_object_unref(). + + + + + 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 bidirectional base direction +for the layout according to the contents of the layout. +See 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 + + + + + + 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. +This does not have an additional refcount added, so if you want to +keep a copy of this around, you must reference it yourself. + + + + + 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. 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. + + + + + + + a #PangoLayout + + + + the byte index of the cursor + + + + location to store the strong cursor position + (may be %NULL) + + + + location to store the weak cursor position (may be %NULL) + + + + + + Gets the type of ellipsization being performed for @layout. +See pango_layout_set_ellipsize() + + + the current ellipsization mode for @layout. + +Use pango_layout_is_ellipsized() to query whether any paragraphs +were actually ellipsized. + + + + + 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 or %NULL to indicate that the result is + not needed. + + + + rectangle used to store the logical + extents of the layout or %NULL to indicate that the + result is not needed. + + + + + + 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. This value is owned by the layout and must + not be modified or freed. + + + + + a #PangoLayout + + + + + + Gets the height of layout used for ellipsization. See +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 that should be freed using + pango_layout_iter_free(). + + + + + a #PangoLayout + + + + + + Gets whether each complete line should be stretched to fill the entire +width of the layout. + + + the justify. + + + + + a #PangoLayout + + + + + + Retrieves a particular line from a #PangoLayout. + +Use the faster 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 + <literal>pango_layout_get_line_count(layout) - 1</literal>, 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 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 + <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive. + + + + + + Returns the lines of the @layout as a list. + +Use the faster 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 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 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 pango_layout_get_extents() followed by +two pango_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 pango_extents_to_pixels()). + + + + + + + a #PangoLayout + + + + rectangle used to store the extents of the + layout as drawn or %NULL to indicate that the result is + not needed. + + + + rectangle used to store the logical + extents of the layout or %NULL to indicate that the + result is not needed. + + + + + + Determines the logical width and height of a #PangoLayout +in device units. (pango_layout_get_size() returns the width +and height scaled by %PANGO_SCALE.) This +is simply a convenience function around +pango_layout_get_pixel_extents(). + + + + + + + a #PangoLayout + + + + location to store the logical width, or %NULL + + + + location to store the logical height, or %NULL + + + + + + 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 pango_layout_context_changed(). + + + The current serial number of @layout. + + + + + a #PangoLayout + + + + + + Obtains the value set by 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 (device units scaled by %PANGO_SCALE). This +is simply a convenience function around pango_layout_get_extents(). + + + + + + + a #PangoLayout + + + + location to store the logical width, or %NULL + + + + location to store the logical height, or %NULL + + + + + + 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 pango_tab_array_free(). + + + a copy of the tabs for this layout, or +%NULL. + + + + + 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 unknown glyphs in @layout. That is, zero if +glyphs for all characters in the layout text were found, or more +than zero otherwise. + +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 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. +(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), or %NULL + + + + location to store resulting position within line + (%PANGO_SCALE units per device unit), or %NULL + + + + + + Converts from an index within a #PangoLayout to the onscreen position +corresponding to the grapheme at that index, which is represented +as rectangle. Note that <literal>pos->x</literal> is always the leading +edge of the grapheme and <literal>pos->x + pos->width</literal> the trailing +edge of the grapheme. If the directionality of the grapheme is right-to-left, +then <literal>pos->width</literal> 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, +ellipsization mode of @layout is set to %PANGO_ELLIPSIZE_NONE, +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 count of positions to move visually. If @direction is positive, +then the new strong cursor position will be one position +to the right of the old cursor position. If @direction is negative, +then the new strong cursor position will be one position +to the left of the old cursor position. + +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 pango_layout_move_cursor_visually() 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 grapheme for the old index + + + + 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. + + + + + + Sets the alignment for the layout: how partial lines are +positioned within the horizontal space available. + + + + + + + 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, can be %NULL + + + + + + Sets whether to calculate the bidirectional base direction +for the layout according to the contents of the layout; +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 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 +pango_layout_set_width() and 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. +See 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, or %NULL 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 first line of each paragraph is ellipsized. +This behvaior may be changed in the future to act per layout instead of per +paragraph. File a bug against pango at <ulink +url="http://bugzilla.gnome.org/">http://bugzilla.gnome.org/</ulink> 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. + + + + + + + a #PangoLayout. + + + + the amount by which to indent. + + + + + + Sets whether each complete line should be stretched to +fill the entire width of the layout. This 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. + + + + + + + a #PangoLayout + + + + whether the lines in the layout should be justified. + + + + + + Same as 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 + null-terminated + + + + + + Sets the layout text and attribute list from marked-up text (see +<link linkend="PangoMarkupFormat">markup format</link>). 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 <link linkend="PangoMarkupFormat">markup format</link>) + + + + length of marked-up text in bytes, or -1 if @markup is + null-terminated + + + + marker for accelerators in the text + + + + return location + for first located accelerator, or %NULL + + + + + + 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. + + + + + + + a #PangoLayout + + + + new setting + + + + + + Sets the amount of spacing in Pango unit between the lines of the +layout. + + + + + + + a #PangoLayout. + + + + the amount of spacing + + + + + + Sets the tabs to use for @layout, overriding the default tabs +(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. + + + + + + + a #PangoLayout + + + + a #PangoTabArray, or %NULL + + + + + + Sets the text of the layout. + +Note that if you have used +pango_layout_set_markup() or pango_layout_set_markup_with_accel() on +@layout before, you may want to call pango_layout_set_attributes() to clear +the attributes set on the layout from the markup as this function does not +clear attributes. + + + + + + + a #PangoLayout + + + + a valid UTF-8 string + + + + 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 +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 pango_layout_set_width(). +To turn off wrapping, set the width to -1. + + + + + + + a #PangoLayout + + + + the wrap mode + + + + + + 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 pango_layout_line_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. + + + + + + + + + + A #PangoLayoutIter structure can be used to +iterate over the visual extents of a #PangoLayout. + +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, + which should be freed with pango_layout_iter_free(), + or %NULL if @iter was %NULL. + + + + + a #PangoLayoutIter, may be %NULL + + + + + + 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 (origin at top left of the entire layout). + + + baseline of current line. + + + + + a #PangoLayoutIter + + + + + + Gets the extents of the current character, in layout coordinates +(origin is 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 +(origin is the top left of the entire layout). + + + + + + + a #PangoLayoutIter + + + + rectangle to fill with ink extents, or %NULL + + + + rectangle to fill with logical extents, or %NULL + + + + + + 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 pango_layout_iter_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. @ink_rect or @logical_rect can be %NULL if you +aren't interested in them. + + + + + + + a #PangoLayoutIter + + + + rectangle to fill with ink extents, + or %NULL + + + + rectangle to fill with logical + extents, or %NULL + + + + + + Gets the current line. + +Use the faster pango_layout_iter_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. @ink_rect or @logical_rect +can be %NULL if you aren't interested in them. 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 pango_layout_line_get_extents(). + + + + + + + a #PangoLayoutIter + + + + rectangle to fill with ink extents, or %NULL + + + + rectangle to fill with logical extents, or %NULL + + + + + + Gets the current line for read-only access. + +This is a faster alternative to pango_layout_iter_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 +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). + + + + + + + a #PangoLayoutIter + + + + start of line, or %NULL + + + + end of line, or %NULL + + + + + + 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 pango_layout_iter_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 extents of the current run in layout coordinates +(origin is the top left of the entire layout). + + + + + + + a #PangoLayoutIter + + + + rectangle to fill with ink extents, or %NULL + + + + rectangle to fill with logical extents, or %NULL + + + + + + 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. + +This is a faster alternative to pango_layout_iter_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 + + + + + + + The #PangoLayoutLine structure represents one of the lines resulting +from laying out a paragraph via #PangoLayout. #PangoLayoutLine +structures are obtained by calling pango_layout_get_line() and +are only valid until the text, attributes, or settings of the +parent #PangoLayout are modified. + +Routines for rendering PangoLayout objects are provided in +code specific to each rendering system. + + + 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 +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, or %NULL + + + + rectangle used to store the logical + extents of the glyph string, or %NULL + + + + + + Computes the logical and ink extents of @layout_line in device units. +This function just calls pango_layout_line_get_extents() followed by +two pango_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 pango_extents_to_pixels()). + + + + + + + a #PangoLayoutLine + + + + rectangle used to store the extents of + the glyph string as drawn, or %NULL + + + + rectangle used to store the logical + extents of the glyph string, or %NULL + + + + + + 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 <literal>2*n_ranges</literal>, + with each range starting at <literal>(*ranges)[2*n]</literal> + and of width <literal>(*ranges)[2*n + 1] - (*ranges)[2*n]</literal>. + 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 unit) + + + + + + Increase the reference count of a #PangoLayoutLine by one. + + + the line passed in. + + + + + a #PangoLayoutLine, may be %NULL + + + + + + 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. + + + + + + + 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 +<ulink url="http://www.unicode.org/reports/tr29/">Grapheme +Cluster Boundaries</ulink> 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 pango_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. +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 +<ulink url="http://www.unicode.org/reports/tr29/">Word +Boundaries</ulink> semantics. (Since: 1.22) + + + + + + + Do not use. Does not do anything. + + + %NULL. + + + + + a #PangoMap + + + + a #PangoScript + + + + + + Do not use. Does not do anything. + + + + + + + a #PangoMap + + + + a #PangoScript + + + + location to store list of engines that exactly + handle this script. + + + + + + location to store list of engines that approximately + handle this script. + + + + + + + + + + + + A structure specifying a transformation between user-space +coordinates and device coordinates. The transformation +is given by + +<programlisting> +x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0; +y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0; +</programlisting> + + + 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, which + should be freed with pango_matrix_free(), or %NULL if + @matrix was %NULL. + + + + + a #PangoMatrix, may be %NULL + + + + + + Free a #PangoMatrix created with pango_matrix_copy(). + + + + + + + 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 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, or %NULL + + + + output scale factor in the x direction, or %NULL + + + + output scale factor perpendicular to the x direction, or %NULL + + + + + + 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 pango_matrix_transform_point() except that the translation +components of the transformation are ignored. The calculation of +the returned vector is as follows: + +<programlisting> +dx2 = dx1 * xx + dy1 * xy; +dy2 = dx1 * yx + dy1 * yy; +</programlisting> + +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, or %NULL + + + + 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. The rectangle should be in device units +(pixels). + +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 pango_matrix_transform_rectangle() on +original rectangle in Pango units and convert to pixels afterward +using pango_extents_to_pixels()'s first argument. + + + + + + + a #PangoMatrix, or %NULL + + + + in/out bounding box in device units, or %NULL + + + + + + Transforms the point (@x, @y) by @matrix. + + + + + + + a #PangoMatrix, or %NULL + + + + in/out X position + + + + in/out Y position + + + + + + First transforms @rect using @matrix, then calculates the bounding box +of the transformed rectangle. The rectangle should be in Pango units. + +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 +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, or %NULL + + + + in/out bounding box in Pango units, or %NULL + + + + + + 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 + + + + + + + A string constant defining the render type +for engines that are not rendering-system specific. + + + + + The #PangoRectangle structure represents a rectangle. It is frequently +used to represent the logical or ink extents of a single glyph or section +of text. (See, for instance, 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 + + + + #PangoRenderer is a base class for objects that are used to +render Pango objects such as #PangoGlyphString and +#PangoLayout. + + + + + + + + + + + + + + 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 +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 (PDF for example). + +Note that @text is the start of the text for layout, which is then +indexed by <literal>@glyph_item->item->offset</literal>. + +If @text is %NULL, this simply calls pango_renderer_draw_glyphs(). + +The default implementation of this method simply falls back to +pango_renderer_draw_glyphs(). + + + + + + + a #PangoRenderer + + + + the UTF-8 text that @glyph_item refers to, or %NULL + + + + 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 +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 in user space coordinates + + + + height of rectangle in Pango units in user space 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 + + + + + + + + + + + + + + + + + Informs Pango that the way that the rendering is done +for @part has changed 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 + +<informalexample><programlisting> +pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); +</programlisting></informalexample> + +When the stipple changes or underlines with different stipples +might be joined together. Pango automatically calls this for +changes to colors. (See pango_renderer_set_color()) + + + + + + + a #PangoRenderer + + + + the part for which rendering has changed. + + + + + + + + + + + + + + + + + + + + Does initial setup before rendering operations on @renderer. +pango_renderer_deactivate() should be called when done drawing. +Calls such as pango_renderer_draw_layout() automatically +activate the layout before drawing on it. Calls to +pango_renderer_activate() and 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 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 +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 (PDF for example). + +Note that @text is the start of the text for layout, which is then +indexed by <literal>@glyph_item->item->offset</literal>. + +If @text is %NULL, this simply calls pango_renderer_draw_glyphs(). + +The default implementation of this method simply falls back to +pango_renderer_draw_glyphs(). + + + + + + + a #PangoRenderer + + + + the UTF-8 text that @glyph_item refers to, or %NULL + + + + 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. + + + + + + + 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. + + + + + + + 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 +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 in user space coordinates + + + + height of rectangle in Pango units in user space 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 + + + + + + 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<!---->() 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<!---->() 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 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 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 + +<informalexample><programlisting> +pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); +</programlisting></informalexample> + +When the stipple changes or underlines with different stipples +might be joined together. Pango automatically calls this for +changes to colors. (See 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 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. + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + 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 in user space coordinates + + + + height of rectangle in Pango units in user space coordinates + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + a #PangoRenderer + + + + the part for which rendering has changed. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #PangoRenderer + + + + the UTF-8 text that @glyph_item refers to, or %NULL + + + + 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 %PANGO_SCALE macro represents 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. +Note that new types may be added in the future. Applications should be ready +to handle unknown values. This enumeration is interchangeable with +#GUnicodeScript. See <ulink +url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex +#24: Script names</ulink>. + + 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 #PangoScript 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. + +As of Pango 1.18, this function simply returns the return value of +g_unichar_get_script(). + + + the #PangoScript for the character. + + + + + a Unicode character + + + + + + Given a script, finds a language tag that is reasonably +representative of that script. This will usually be the +most widely spoken or used language written in that script: +for instance, the sample language for %PANGO_SCRIPT_CYRILLIC +is <literal>ru</literal> (Russian), the sample language +for %PANGO_SCRIPT_ARABIC is <literal>ar</literal>. + +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 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, or %NULL if no such language exists. + + + + + a #PangoScript + + + + + + + A #PangoScriptIter is used to iterate through a string +and identify ranges in different scripts. + + + Frees a #PangoScriptIter created with pango_script_iter_new(). + + + + + + + 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) + + + + + + + a #PangoScriptIter + + + + location to store start position of the range, or %NULL + + + + location to store end position of the range, or %NULL + + + + location to store script for range, or %NULL + + + + + + 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 + + + + + + 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 pango_script_iter_free(). + + + the new script iterator, initialized + to point at the first range in the text, which should be + freed with pango_script_iter_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. + + + + + + + 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. + + + + A #PangoTabAlign specifies where a tab stop appears relative to the text. + + the tab stop appears to the left of the text. + + + + A #PangoTabArray struct contains an array +of tab stops. Each tab stop has an alignment and a position. + + + 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 pango_tab_array_free(). + + + + + Initial number of tab stops to allocate, can be 0 + + + + whether positions are in pixel units + + + + + + This is a convenience function that creates a #PangoTabArray +and allows you to specify the alignment and position of each +tab stop. You <emphasis>must</emphasis> provide an alignment +and position for @size tab stops. + + + the newly allocated #PangoTabArray, which should + be freed with pango_tab_array_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 pango_tab_array_free(). + + + + + #PangoTabArray to copy + + + + + + Frees a tab array and associated resources. + + + + + + + a #PangoTabArray + + + + + + 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, or %NULL + + + + location to store tab position, or %NULL + + + + + + If non-%NULL, @alignments and @locations are filled with allocated +arrays of length pango_tab_array_get_size(). You must free the +returned array. + + + + + + + a #PangoTabArray + + + + location to store an array of tab + stop alignments, or %NULL + + + + location to store an array + of tab positions, or %NULL + + + + + + + + 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 alignment and location of a tab stop. +@alignment must always be #PANGO_TAB_LEFT in the current +implementation. + + + + + + + a #PangoTabArray + + + + the index of a tab stop + + + + tab alignment + + + + tab location 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. + + + a wavy underline should be drawn below. +This underline is typically used to indicate +an error such as a possilble mispelling; in some +cases a contrasting color may automatically +be used. This type of underlining is available since Pango 1.4. + + + + A macro that should be defined by the user prior to including +the pango.h header. +The definition should be one of the predefined Pango version +macros: %PANGO_VERSION_1_2, %PANGO_VERSION_1_4,... + +This macro defines the earliest version of Pango 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 +%PANGO_VERSION_MIN_REQUIRED or earlier will cause warnings (but +using functions deprecated in later releases will not). + + + + + 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. + + + + An enumeration specifying the weight (boldness) of a font. This is a numerical +value ranging from 100 to 1000, but there are some 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 normal 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) + + + + A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width. + + 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. + + + + Create a new background alpha attribute. + + + the new allocated #PangoAttribute, + which should be freed with 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 pango_attribute_destroy(). + + + + + the red value (ranging from 0 to 65535) + + + + the green value + + + + the blue value + + + + + + 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 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 pango_attribute_destroy(). + + + + + the family or comma separated list of families + + + + + + Create a new foreground alpha attribute. + + + the new allocated #PangoAttribute, + which should be freed with 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 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 pango_attribute_destroy(). + + + + + the gravity hint value. + + + + + + Create a new gravity attribute. + + + the newly allocated #PangoAttribute, + which should be freed with pango_attribute_destroy(). + + + + + the gravity value; should not be %PANGO_GRAVITY_AUTO. + + + + + + Create a new letter-spacing attribute. + + + the newly allocated #PangoAttribute, + which should be freed with pango_attribute_destroy(). + + + + + amount of extra space to add between graphemes + of the text, in Pango units. + + + + + + Create a new baseline displacement attribute. + + + the newly allocated #PangoAttribute, + which should be freed with 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 pango_attribute_destroy(). + + + + + factor to scale the font + + + + + + Create a new font stretch attribute + + + the newly allocated #PangoAttribute, + which should be freed with 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 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 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 pango_attribute_destroy(). + + + + + the slant style + + + + + + Fetches the attribute type name passed in when registering the type using +pango_attr_type_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 pango_attr_type_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 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 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 pango_attribute_destroy(). + + + + + the variant + + + + + + Create a new font weight attribute. + + + the newly allocated #PangoAttribute, + which should be freed with pango_attribute_destroy(). + + + + + the weight + + + + + + Determines the normative bidirectional character type of a +character, as specified in the Unicode Character Database. + +A simplified version of this function is available as +pango_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 pango_get_log_attrs(). + + + + + + + the text to process + + + + length of @text in bytes (may be -1 if @text is nul-terminated) + + + + #PangoAnalysis structure from pango_itemize() + + + + an array to store character + information in + + + + + + size of the array passed as @attrs + + + + + + Do not use. Does not do anything. + + + %NULL + + + + + Key to look up, in the form "SECTION/KEY". + + + + + + Do not use. Does not do anything. + + + %NULL + + + + + Key to look up, in the form "SECTION/KEY". + + + + + + This is the default break algorithm, used if no language +engine overrides it. Normally you should use pango_break() +instead. Unlike pango_break(), +@analysis can be %NULL, but only do that if you know what +you're doing. If you need an analysis to pass to pango_break(), +you need to pango_itemize(). In most cases however you should +simply use pango_get_log_attrs(). + + + + + + + text to break + + + + length of text in bytes (may be -1 if @text is nul-terminated) + + + + a #PangoAnalysis for the @text + + + + logical attributes to fill in + + + + size of the array passed as @attrs + + + + + + Converts extents from Pango units to device units, 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, or %NULL. + + + + rectangle to round to nearest pixels, or %NULL. + + + + + + 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 + + + + length of @text in bytes (may be -1 if @text is nul-terminated) + + + + + + Do not use. Does not do anything. + + + %NULL. + + + + + the language tag for which to find the map + + + + the engine type for the map to find + + + + the render type for the map to find + + + + + + 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 paragraph +(index after all delimiters) is stored in @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 in the +form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", 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. 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 new #PangoFontDescription. + + + + + string representation of a font description. + + + + + + Returns the name of the "pango" subdirectory of LIBDIR +(which is set at compile time). + + + the Pango lib directory. The returned string should +not be freed. + + + + + Computes a #PangoLogAttr for each character in @text. The @log_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 + + + + 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 @log_attrs array + + + + + + 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, puts that character in the address pointed to by @mirrored_ch. + +Use g_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 + + + + + + Returns the name of the "pango" subdirectory of SYSCONFDIR +(which is set at compile time). + + + the Pango sysconf directory. The returned string should +not be freed. + + + + + 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 + + + + + + Based on the script, base gravity, and hint, returns actual gravity +to use in laying out a single #PangoItem. + +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 + + + + + + Based on the script, East Asian width, base gravity, and hint, +returns actual gravity to use in laying out a single character +or #PangoItem. + +This function is similar to 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 <emphasis>upright</emphasis>, 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. +@gravity should not be %PANGO_GRAVITY_AUTO. + +Note that pango_matrix_rotate() takes angle in degrees, not radians. +So, to call 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 + + + + + + Checks @ch to see if it is a character that should not be +normally rendered on the screen. This includes all Unicode characters +with "ZERO WIDTH" in their name, as well as <firstterm>bidi</firstterm> formatting characters, and +a few other ones. This is totally different from g_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 shaping engine. 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 #PangoItem + structures. The items should be freed using pango_item_free() + probably in combination with g_list_foreach(), and the list itself + using g_list_free(). + + + + + + + a structure holding information that affects + the itemization process. + + + + 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, or %NULL + + + + + + Like pango_itemize(), but the base direction to use when +computing bidirectional levels (see pango_context_set_base_dir ()), +is specified explicitly rather than gotten from the #PangoContext. + + + a #GList of + #PangoItem structures. The items should be freed using + pango_item_free() probably in combination with + g_list_foreach(), and the list itself using g_list_free(). + + + + + + + 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, or %NULL + + + + + + Take a RFC-3066 format language tag as a string and convert it to a +#PangoLanguage pointer that 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 pango_language_get_default() if you want to get the #PangoLanguage for +the current locale of the process. + + + an opaque pointer to a + #PangoLanguage structure, or %NULL if @language was + %NULL. The returned pointer will be valid forever + after, and should not be freed. + + + + + a string representing a language tag, or %NULL + + + + + + Returns the #PangoLanguage for the current locale of the process. +Note that this can change over the life of an application. + +On Unix systems, this is the return value is derived from +<literal>setlocale(LC_CTYPE, NULL)</literal>, 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 <literal>setlocale(LC_ALL, "");</literal> +for the user settings to take effect. Gtk+ does this in its initialization +functions automatically (by calling gtk_set_locale()). +See <literal>man setlocale</literal> for more details. + + + the default language as a + #PangoLanguage, must not be freed. + + + + + This will return the bidirectional embedding levels of the input paragraph +as defined by the Unicode Bidirectional Algorithm available at: + + 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 g_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. + + + + + + Look up all user defined aliases for the alias @fontname. +The resulting font family names will be stored in @families, +and the number of families in @n_families. + This function is not thread-safe. + + + + + + + an ascii string + + + + will be set to an array of font family names. + this array is owned by pango and should not be freed. + + + + + + will be set to the length of the @families array. + + + + + + After feeding a pango markup parser some data with g_markup_parse_context_parse(), +use this function to get the list of pango attributes and text out of the +markup. This function will not free @context, use g_markup_parse_context_free() +to do so. + + + %FALSE if @error is set, otherwise %TRUE + + + + + A valid parse context that was returned from pango_markup_parser_new() + + + + address of return location for a #PangoAttrList, or %NULL + + + + address of return location for text with tags stripped, or %NULL + + + + address of return location for accelerator char, or %NULL + + + + + + Parses marked-up text (see +<link linkend="PangoMarkupFormat">markup format</link>) to create +a plain-text string and an 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, +when calling finish(). Two @accel_marker characters following each +other produce a single literal @accel_marker character. + +To feed markup to the parser, use g_markup_parse_context_parse() +on the returned #GMarkupParseContext. When done with feeding markup +to the parser, use pango_markup_parser_finish() to get the data out +of it, and then use g_markup_parse_context_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 simpler pango_parse_markup() API is recommended instead. + + + a #GMarkupParseContext that should be +destroyed with g_markup_parse_context_free(). + + + + + character that precedes an accelerator, or 0 for none + + + + + + Do not use. Does not do anything. + + + + + + + a #PangoIncludedModule + + + + + + 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. May be %NULL. + + + + integer to store the result in, or %NULL. + + + + if %TRUE, issue a g_warning() on bad input. + + + + place to store list of possible values on failure, or %NULL. + + + + + + Parses marked-up text (see +<link linkend="PangoMarkupFormat">markup format</link>) to create +a plain-text string and an 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. + +To parse a stream of pango markup incrementally, use pango_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 <link linkend="PangoMarkupFormat">markup format</link>) + + + + 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, or %NULL + + + + address of return location for text with tags stripped, or %NULL + + + + address of return location for accelerator char, or %NULL + + + + + + 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" +and "smallcaps" or "small_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, typically an +underline or strikethrough, to whole device pixels, that is integer +multiples of %PANGO_SCALE. 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 + + + + + + From a list of items in logical order and the associated +directional levels, produce a list in visual order. +The original list is unmodified. + + + a #GList + of #PangoItem structures in visual order. + +(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 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 #PangoScript 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. + +As of Pango 1.18, this function simply returns the return value of +g_unichar_get_script(). + + + the #PangoScript for the character. + + + + + a Unicode character + + + + + + Given a script, finds a language tag that is reasonably +representative of that script. This will usually be the +most widely spoken or used language written in that script: +for instance, the sample language for %PANGO_SCRIPT_CYRILLIC +is <literal>ru</literal> (Russian), the sample language +for %PANGO_SCRIPT_ARABIC is <literal>ar</literal>. + +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 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, or %NULL if no such language exists. + + + + + a #PangoScript + + + + + + Given a segment of text and the corresponding +#PangoAnalysis structure returned from pango_itemize(), +convert the characters into glyphs. You may also pass +in only a substring of the item from pango_itemize(). + +It is recommended that you use pango_shape_full() instead, since +that API allows for shaping interaction happening across text item +boundaries. + + + + + + + the text to process + + + + the length (in bytes) of @text + + + + #PangoAnalysis structure from pango_itemize() + + + + glyph string in which to store results + + + + + + Given a segment of text and the corresponding +#PangoAnalysis structure returned from pango_itemize(), +convert the characters into glyphs. You may also pass +in only a substring of the item from pango_itemize(). + +This is similar to 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. + + + + + + + valid UTF-8 text to shape. + + + + the length (in bytes) of @item_text. -1 means nul-terminated text. + + + + text of the paragraph (see details). May be %NULL. + + + + the length (in bytes) of @paragraph_text. -1 means nul-terminated text. + + + + #PangoAnalysis structure from pango_itemize(). + + + + glyph string in which to store results. + + + + + + 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 + + + + + + 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; 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, +pango_bidi_type_for_unichar() can be used instead. + + + the direction of the character. + + + + + a Unicode character + + + + + + Converts a floating-point number to Pango units: multiplies +it by %PANGO_SCALE and rounds to nearest integer. + + + the value in Pango units. + + + + + double floating-point value + + + + + + Converts a number in Pango units to floating-point: divides +it by %PANGO_SCALE. + + + the double value. + + + + + value in Pango units + + + + + + This is similar to the macro %PANGO_VERSION except that +it returns the encoded version of Pango available at run-time, +as opposed to the 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. + + + + + + This is similar to the macro %PANGO_VERSION_STRING except that +it returns the version of Pango available at run-time, as opposed to +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. + + + + + diff --git a/gir-files/PangoCairo-1.0.gir b/gir-files/PangoCairo-1.0.gir new file mode 100644 index 0000000..93c0b59 --- /dev/null +++ b/gir-files/PangoCairo-1.0.gir @@ -0,0 +1,738 @@ + + + + + + + + + + + #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, + or %NULL if @font is %NULL. + + + + + 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 +pango_cairo_font_map_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 pango_cairo_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 @pango_cairo_font_map_new(), +or in fact in most of those cases, just use +@pango_cairo_font_map_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 pango_cairo_font_map_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 exisiting threads +are not changed. Default fontmaps of any new threads will +still be created using pango_cairo_font_map_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 pango_cairo_font_map_new(). + + + + + + + The new default font map, or %NULL + + + + + + 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 +pango_cairo_context_set_font_options(). This function does not report options +that are derived from the target surface by pango_cairo_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 pango_cairo_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 +pango_cairo_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 pango_cairo_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, or %NULL. + + + + + + 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 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 pango_cairo_create_layout() instead. + + + the newly created #PangoContext. Free with + g_object_unref(). + + + + + 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 +pango_layout_get_size() or drawing with functions like +pango_cairo_show_layout(). If you change the transformation +or target surface for @cr, you need to call pango_cairo_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. Free with + g_object_unref(). + + + + + 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 +pango_cairo_font_map_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 pango_cairo_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 @pango_cairo_font_map_new(), +or in fact in most of those cases, just use +@pango_cairo_font_map_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 pango_cairo_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 <literal>@glyph_item->item->offset</literal>. + + + + + + + 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 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 +pango_cairo_create_layout() to match the current transformation +and target surface of a Cairo context. + + + + + + + a Cairo context + + + + a #PangoLayout, from pango_cairo_create_layout() + + + + + + diff --git a/gir-files/PangoFT2-1.0.gir b/gir-files/PangoFT2-1.0.gir new file mode 100644 index 0000000..9d04198 --- /dev/null +++ b/gir-files/PangoFT2-1.0.gir @@ -0,0 +1,338 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Function type for doing final config tweaking on prepared FcPatterns. + + + + + + + the <type>FcPattern</type> to tweak. + + + + user data. + + + + + + Gets the #PangoCoverage for a <type>PangoFT2Font</type>. Use +pango_font_get_coverage() instead. + + + a #PangoCoverage. + + + + + a <type>PangoFT2Font</type>. + + + + a language tag. + + + + + + Returns the native FreeType2 <type>FT_Face</type> structure used for this #PangoFont. +This may be useful if you want to use FreeType2 functions directly. + +Use pango_fc_font_lock_face() instead; when you are done with a +face from pango_fc_font_lock_face() you must call +pango_fc_font_unlock_face(). + + + a pointer to a <type>FT_Face</type> + structure, with the size set correctly, or %NULL if + @font is %NULL. + + + + + 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 + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/PangoXft-1.0.gir b/gir-files/PangoXft-1.0.gir new file mode 100644 index 0000000..3658085 --- /dev/null +++ b/gir-files/PangoXft-1.0.gir @@ -0,0 +1,636 @@ + + + + + + + + + + + + + #PangoXftFont is an implementation of #PangoFcFont using the Xft +library for rendering. It is used in conjunction with #PangoXftFontMap. + + Returns the X display of the XftFont of a font. + + + the X display of the XftFont associated to @font. + + + + + a #PangoFont. + + + + + + Returns the XftFont of a font. + + + the XftFont associated to @font, or %NULL +if @font is %NULL. + + + + + 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 <type>FT_Face</type> 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 <type>FT_Face</type> 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, which should + be freed with g_object_unref(). + + + + + 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 <type>Picture</type> 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 <type>XftDraw</type> object wrapping an X drawable. + + + + + + + the <type>XftDraw</type> 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, or %NULL to use an identity + transformation + + + + 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. + + + + + + + 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. + + + + + + + an X Display + + + + the screen number of a screen within @display + + + + + + diff --git a/gir-files/README.md b/gir-files/README.md new file mode 100644 index 0000000..d8437f7 --- /dev/null +++ b/gir-files/README.md @@ -0,0 +1,11 @@ +# gir-files + +This repository is used to generate all `gtk-rs` crates. It contains the definitions of the GNOME libraries' APIs. + +If a new GTK version was released, you can update the files by doing so: + +```bash +./dl.sh && ./fix.sh +``` + +Please don't forget to check that [`gir`](https://github.com/gtk-rs/gir) can still run with the new files since breaking changes can appear. diff --git a/gir-files/Secret-1.gir b/gir-files/Secret-1.gir new file mode 100644 index 0000000..eac0d70 --- /dev/null +++ b/gir-files/Secret-1.gir @@ -0,0 +1,6240 @@ + + + + + + + + + + + + + + + + + + + + + + + + An alias to the default collection. This can be passed to secret_password_store() +secret_collection_for_alias(). + + + + + + + + + + + + An alias to the session collection, which will be cleared when the user ends +the session. This can be passed to secret_password_store(), +secret_collection_for_alias() or similar functions. + + + + + A proxy object representing a collection of secrets in the Secret Service. + + + + + + Finish asynchronous operation to get a new collection proxy for a +collection in the secret service. + + + the new collection, which should be unreferenced + with g_object_unref() + + + + + the asynchronous result passed to the callback + + + + + + Get a new collection proxy for a collection in the secret service. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block indefinitely and should not be used in user interface +threads. + + + the new collection, which should be unreferenced + with g_object_unref() + + + + + a secret service object + + + + the D-Bus path of the collection + + + + options for the collection initialization + + + + optional cancellation object + + + + + + Create a new collection in the secret service. + +This method returns immediately and completes asynchronously. The secret +service may prompt the user. secret_service_prompt() will be used to handle +any prompts that are required. + +An @alias is a well-known tag for a collection, such as 'default' (ie: the +default collection to store items in). This allows other applications to +easily identify and share a collection. If you specify an @alias, and a +collection with that alias already exists, then a new collection will not +be created. The previous one will be returned instead. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + + + + + + + a secret service object + + + + label for the new collection + + + + alias to assign to the collection + + + + currently unused + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Finish operation to create a new collection in the secret service. + + + the new collection, which should be unreferenced + with g_object_unref() + + + + + the asynchronous result passed to the callback + + + + + + Create a new collection in the secret service. + +This method may block indefinitely and should not be used in user interface +threads. The secret service may prompt the user. secret_service_prompt() +will be used to handle any prompts that are required. + +An @alias is a well-known tag for a collection, such as 'default' (ie: the +default collection to store items in). This allows other applications to +easily identify and share a collection. If you specify an @alias, and a +collection with that alias already exists, then a new collection will not +be created. The previous one will be returned instead. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + + + the new collection, which should be unreferenced + with g_object_unref() + + + + + a secret service object + + + + label for the new collection + + + + alias to assign to the collection + + + + currently unused + + + + optional cancellation object + + + + + + Lookup which collection is assigned to this alias. Aliases help determine +well known collections, such as 'default'. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +This method will return immediately and complete asynchronously. + + + + + + + a secret service object + + + + the alias to lookup + + + + options for the collection initialization + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Finish an asynchronous operation to lookup which collection is assigned +to an alias. + + + the collection, or %NULL if none assigned to the alias + + + + + asynchronous result passed to callback + + + + + + Lookup which collection is assigned to this alias. Aliases help determine +well known collections, such as 'default'. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block and should not be used in user interface threads. + + + the collection, or %NULL if none assigned to the alias + + + + + a secret service object + + + + the alias to lookup + + + + options for the collection initialization + + + + optional cancellation object + + + + + + Get a new collection proxy for a collection in the secret service. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +This method will return immediately and complete asynchronously. + + + + + + + a secret service object + + + + the D-Bus path of the collection + + + + options for the collection initialization + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Delete this collection. + +This method returns immediately and completes asynchronously. The secret +service may prompt the user. secret_service_prompt() will be used to handle +any prompts that show up. + + + + + + + a collection + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete operation to delete this collection. + + + whether the collection was successfully deleted or not + + + + + a collection + + + + asynchronous result passed to the callback + + + + + + Delete this collection. + +This method may block indefinitely and should not be used in user +interface threads. The secret service may prompt the user. +secret_service_prompt() will be used to handle any prompts that show up. + + + whether the collection was successfully deleted or not + + + + + a collection + + + + optional cancellation object + + + + + + Get the created date and time of the collection. The return value is +the number of seconds since the unix epoch, January 1st 1970. + + + the created date and time + + + + + a collection + + + + + + Get the flags representing what features of the #SecretCollection proxy +have been initialized. + +Use secret_collection_load_items() to initialize further features +and change the flags. + + + the flags for features initialized + + + + + the secret collection proxy + + + + + + Get the list of items in this collection. + + + a list of items, +when done, the list should be freed with g_list_free, and each item should +be released with g_object_unref() + + + + + + + a collection + + + + + + Get the label of this collection. + + + the label, which should be freed with g_free() + + + + + a collection + + + + + + Get whether the collection is locked or not. + +Use secret_service_lock() or secret_service_unlock() to lock or unlock the +collection. + + + whether the collection is locked or not + + + + + a collection + + + + + + Get the modified date and time of the collection. The return value is +the number of seconds since the unix epoch, January 1st 1970. + + + the modified date and time + + + + + a collection + + + + + + Get the Secret Service object that this collection was created with. + + + the Secret Service object + + + + + a collection + + + + + + Ensure that the #SecretCollection proxy has loaded all the items present +in the Secret Service. This affects the result of +secret_collection_get_items(). + +For collections returned from secret_service_get_collections() the items +will have already been loaded. + +This method will return immediately and complete asynchronously. + + + + + + + the secret collection + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Complete an asynchronous operation to ensure that the #SecretCollection proxy +has loaded all the items present in the Secret Service. + + + whether the load was successful or not + + + + + the secret collection + + + + the asynchronous result passed to the callback + + + + + + Ensure that the #SecretCollection proxy has loaded all the items present +in the Secret Service. This affects the result of +secret_collection_get_items(). + +For collections returned from secret_service_get_collections() the items +will have already been loaded. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether the load was successful or not + + + + + the secret collection + + + + optional cancellation object + + + + + + Refresh the properties on this collection. This fires off a request to +refresh, and the properties will be updated later. + +Calling this method is not normally necessary, as the secret service +will notify the client when properties change. + + + + + + + the collection + + + + + + Search for items matching the @attributes in the @collection. +The @attributes should be a table of string keys and string values. + +If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the +search will be returned. Otherwise only the first item will be returned. +This is almost always the unlocked item that was most recently stored. + +If %SECRET_SEARCH_UNLOCK is set in @flags, then items will be unlocked +if necessary. In either case, locked and unlocked items will match the +search and be returned. If the unlock fails, the search does not fail. + +If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have +their secret values loaded and available via secret_item_get_secret(). + +This function returns immediately and completes asynchronously. + + + + + + + a secret collection + + + + the schema for the attributes + + + + search for items matching these attributes + + + + + + + search option flags + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to search for items in a collection. + + + + a list of items that matched the search + + + + + + + the secret collection + + + + asynchronous result passed to callback + + + + + + Search for items in @collection matching the @attributes, and return their +DBus object paths. Only the specified collection is searched. The @attributes +should be a table of string keys and string values. + +This function returns immediately and completes asynchronously. + +When your callback is called use secret_collection_search_for_dbus_paths_finish() +to get the results of this function. Only the DBus object paths of the +items will be returned. If you would like #SecretItem objects to be returned +instead, then use the secret_collection_search() function. + + + + + + + the secret collection + + + + the schema for the attributes + + + + search for items matching these attributes + + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to search for items in a collection. + +DBus object paths of the items will be returned. If you would to have +#SecretItem objects to be returned instead, then use the +secret_collection_search() and secret_collection_search_finish() functions. + + + an array of DBus object + paths for matching items. + + + + + + + the secret collection + + + + asynchronous result passed to callback + + + + + + Search for items matching the @attributes in @collection, and return their +DBus object paths. The @attributes should be a table of string keys and +string values. + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + +DBus object paths of the items will be returned. If you would to have +#SecretItem objects to be returned instead, then use the +secret_collection_search_sync() function. + + + an array of DBus object + paths for matching items. + + + + + + + the secret collection + + + + the schema for the attributes + + + + search for items matching these attributes + + + + + + + optional cancellation object + + + + + + Search for items matching the @attributes in the @collection. +The @attributes should be a table of string keys and string values. + +If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the +search will be returned. Otherwise only the first item will be returned. +This is almost always the unlocked item that was most recently stored. + +If %SECRET_SEARCH_UNLOCK is set in @flags, then items will be unlocked +if necessary. In either case, locked and unlocked items will match the +search and be returned. If the unlock fails, the search does not fail. + +If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have +their secret values loaded and available via secret_item_get_secret(). + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + + + + a list of items that matched the search + + + + + + + a secret collection + + + + the schema for the attributes + + + + search for items matching these attributes + + + + + + + search option flags + + + + optional cancellation object + + + + + + Set the label of this collection. + +This function returns immediately and completes asynchronously. + + + + + + + a collection + + + + a new label + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to set the label of this collection. + + + whether the change was successful or not + + + + + a collection + + + + asynchronous result passed to callback + + + + + + Set the label of this collection. + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + + + whether the change was successful or not + + + + + a collection + + + + a new label + + + + optional cancellation object + + + + + + The date and time (in seconds since the UNIX epoch) that this +collection was created. + + + + A set of flags describing which parts of the secret collection have +been initialized. + + + + A list of #SecretItem objects representing the items that are in +this collection. This list will be empty if the collection is locked. + + + + The human readable label for the collection. + +Setting this property will result in the label of the collection being +set asynchronously. To properly track the changing of the label use the +secret_collection_set_label() function. + + + + Whether the collection is locked or not. + +To lock or unlock a collection use the secret_service_lock() or +secret_service_unlock() functions. + + + + The date and time (in seconds since the UNIX epoch) that this +collection was last modified. + + + + The #SecretService object that this collection is associated with and +uses to interact with the actual D-Bus Secret Service. + + + + + + + + + + + The class for #SecretCollection. + + + the parent class + + + + + + + + + + Flags for secret_collection_create(). + + + no flags + + + + Flags which determine which parts of the #SecretCollection proxy are initialized. + + + no flags + + + items have or should be loaded + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A proxy object representing a secret item in the Secret Service. + + + + + + Finish asynchronous operation to get a new item proxy for a secret +item in the secret service. + + + the new item, which should be unreferenced + with g_object_unref() + + + + + the asynchronous result passed to the callback + + + + + + Get a new item proxy for a secret item in the secret service. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block indefinitely and should not be used in user interface +threads. + + + the new item, which should be unreferenced + with g_object_unref() + + + + + a secret service object + + + + the D-Bus path of the item + + + + initialization flags for the new item + + + + optional cancellation object + + + + + + Create a new item in the secret service. + +If the @flags contains %SECRET_ITEM_CREATE_REPLACE, then the secret +service will search for an item matching the @attributes, and update that item +instead of creating a new one. + +This method may block indefinitely and should not be used in user interface +threads. The secret service may prompt the user. secret_service_prompt() +will be used to handle any prompts that are required. + + + + + + + a secret collection to create this item in + + + + the schema for the attributes + + + + attributes for the new item + + + + + + + label for the new item + + + + secret value for the new item + + + + flags for the creation of the new item + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Finish operation to create a new item in the secret service. + + + the new item, which should be unreferenced + with g_object_unref() + + + + + the asynchronous result passed to the callback + + + + + + Create a new item in the secret service. + +If the @flags contains %SECRET_ITEM_CREATE_REPLACE, then the secret +service will search for an item matching the @attributes, and update that item +instead of creating a new one. + +This method may block indefinitely and should not be used in user interface +threads. The secret service may prompt the user. secret_service_prompt() +will be used to handle any prompts that are required. + + + the new item, which should be unreferenced + with g_object_unref() + + + + + a secret collection to create this item in + + + + the schema for the attributes + + + + attributes for the new item + + + + + + + label for the new item + + + + secret value for the new item + + + + flags for the creation of the new item + + + + optional cancellation object + + + + + + Load the secret values for a secret item stored in the service. + +The @items must all have the same SecretItem::service property. + +This function returns immediately and completes asynchronously. + + + + + + + the items to retrieve secrets for + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to load the secret values for +secret items stored in the service. + +Items that are locked will not have their secrets loaded. + + + whether the operation succeeded or not + + + + + asynchronous result passed to callback + + + + + + Load the secret values for a secret item stored in the service. + +The @items must all have the same SecretItem::service property. + +This method may block indefinitely and should not be used in user interface +threads. + +Items that are locked will not have their secrets loaded. + + + whether the operation succeeded or not + + + + + the items to retrieve secrets for + + + + + + optional cancellation object + + + + + + Get a new item proxy for a secret item in the secret service. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +This method will return immediately and complete asynchronously. + + + + + + + a secret service object + + + + the D-Bus path of the collection + + + + initialization flags for the new item + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Delete this item. + +This method returns immediately and completes asynchronously. The secret +service may prompt the user. secret_service_prompt() will be used to handle +any prompts that show up. + + + + + + + an item + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to delete the secret item. + + + whether the item was successfully deleted or not + + + + + an item + + + + asynchronous result passed to the callback + + + + + + Delete this secret item. + +This method may block indefinitely and should not be used in user +interface threads. The secret service may prompt the user. +secret_service_prompt() will be used to handle any prompts that show up. + + + whether the item was successfully deleted or not + + + + + an item + + + + optional cancellation object + + + + + + Set the attributes of this item. + +The @attributes are a mapping of string keys to string values. +Attributes are used to search for items. Attributes are not stored +or transferred securely by the secret service. + +Do not modify the attributes returned by this method. Use +secret_item_set_attributes() instead. + + + a new reference + to the attributes, which should not be modified, and + released with g_hash_table_unref() + + + + + + + + an item + + + + + + Get the created date and time of the item. The return value is +the number of seconds since the unix epoch, January 1st 1970. + + + the created date and time + + + + + an item + + + + + + Get the flags representing what features of the #SecretItem proxy +have been initialized. + +Use secret_item_load_secret() to initialize further features +and change the flags. + + + the flags for features initialized + + + + + the secret item proxy + + + + + + Get the label of this item. + + + the label, which should be freed with g_free() + + + + + an item + + + + + + Get whether the item is locked or not. + +Depending on the secret service an item may not be able to be locked +independently from the collection that it is in. + + + whether the item is locked or not + + + + + an item + + + + + + Get the modified date and time of the item. The return value is +the number of seconds since the unix epoch, January 1st 1970. + + + the modified date and time + + + + + an item + + + + + + Gets the name of the schema that this item was stored with. This is also +available at the <literal>xdg:schema</literal> attribute. + + + the schema name + + + + + an item + + + + + + Get the secret value of this item. If this item is locked or the secret +has not yet been loaded then this will return %NULL. + +To load the secret call the secret_item_load_secret() method. + + + the secret value which should be + released with secret_value_unref(), or %NULL + + + + + an item + + + + + + Get the Secret Service object that this item was created with. + + + the Secret Service object + + + + + an item + + + + + + Load the secret value of this item. + +Each item has a single secret which might be a password or some +other secret binary value. + +This function will fail if the secret item is locked. + +This function returns immediately and completes asynchronously. + + + + + + + an item proxy + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to load the secret value of this item. + +The newly loaded secret value can be accessed by calling +secret_item_get_secret(). + + + whether the secret item successfully loaded or not + + + + + an item proxy + + + + asynchronous result passed to callback + + + + + + Load the secret value of this item. + +Each item has a single secret which might be a password or some +other secret binary value. + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + + + whether the secret item successfully loaded or not + + + + + an item + + + + optional cancellation object + + + + + + Refresh the properties on this item. This fires off a request to +refresh, and the properties will be updated later. + +Calling this method is not normally necessary, as the secret service +will notify the client when properties change. + + + + + + + the collection + + + + + + Set the attributes of this item. + +The @attributes are a mapping of string keys to string values. +Attributes are used to search for items. Attributes are not stored +or transferred securely by the secret service. + +This function returns immediately and completes asynchronously. + + + + + + + an item + + + + the schema for the attributes + + + + a new set of attributes + + + + + + + optional cancellation object + + + + called when the asynchronous operation completes + + + + data to pass to the callback + + + + + + Complete operation to set the attributes of this item. + + + whether the change was successful or not + + + + + an item + + + + asynchronous result passed to the callback + + + + + + Set the attributes of this item. + +The @attributes are a mapping of string keys to string values. +Attributes are used to search for items. Attributes are not stored +or transferred securely by the secret service. + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + + + whether the change was successful or not + + + + + an item + + + + the schema for the attributes + + + + a new set of attributes + + + + + + + optional cancellation object + + + + + + Set the label of this item. + +This function returns immediately and completes asynchronously. + + + + + + + an item + + + + a new label + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to set the label of this collection. + + + whether the change was successful or not + + + + + an item + + + + asynchronous result passed to callback + + + + + + Set the label of this item. + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + + + whether the change was successful or not + + + + + an item + + + + a new label + + + + optional cancellation object + + + + + + Set the secret value of this item. + +Each item has a single secret which might be a password or some +other secret binary value. + +This function returns immediately and completes asynchronously. + + + + + + + an item + + + + a new secret value + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to set the secret value of this item. + + + whether the change was successful or not + + + + + an item + + + + asynchronous result passed to callback + + + + + + Set the secret value of this item. + +Each item has a single secret which might be a password or some +other secret binary value. + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + + + whether the change was successful or not + + + + + an item + + + + a new secret value + + + + optional cancellation object + + + + + + The attributes set on this item. Attributes are used to locate an +item. They are not guaranteed to be stored or transferred securely. + + + + + + + The date and time (in seconds since the UNIX epoch) that this +item was created. + + + + A set of flags describing which parts of the secret item have +been initialized. + + + + The human readable label for the item. + +Setting this property will result in the label of the item being +set asynchronously. To properly track the changing of the label use the +secret_item_set_label() function. + + + + Whether the item is locked or not. An item may not be independently +lockable separate from other items in its collection. + +To lock or unlock a item use the secret_service_lock() or +secret_service_unlock() functions. + + + + The date and time (in seconds since the UNIX epoch) that this +item was last modified. + + + + The #SecretService object that this item is associated with and +uses to interact with the actual D-Bus Secret Service. + + + + + + + + + + + The class for #SecretItem. + + + the parent class + + + + + + + + + + Flags for secret_item_create(). + + + no flags + + + replace an item with the same attributes. + + + + Flags which determine which parts of the #SecretItem proxy are initialized. + + + no flags + + + a secret has been (or should be) loaded for #SecretItem + + + + + + + + + + + + + + + + + + + + + + + + + + + + A proxy object representing a prompt that the Secret Service will display +to the user. + + + + + + Runs a prompt and performs the prompting. Returns %TRUE if the prompt +was completed and not dismissed. + +If @window_id is non-null then it is used as an XWindow id on Linux. The API +expects this id to be converted to a string using the <literal>%d</literal> +printf format. The Secret Service can make its prompt transient for the window +with this id. In some Secret Service implementations this is not possible, so +the behavior depending on this should degrade gracefully. + +This method will return immediately and complete asynchronously. + + + + + + + a prompt + + + + string form of XWindow id for parent window to be transient for + + + + the variant type of the prompt result + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Complete asynchronous operation to run a prompt and perform the prompting. + +Returns a variant result if the prompt was completed and not dismissed. The +type of result depends on the action the prompt is completing, and is +defined in the Secret Service DBus API specification. + + + %NULL if the prompt was dismissed or an error occurred, + a variant result if the prompt was successful + + + + + a prompt + + + + the asynchronous result passed to the callback + + + + + + Runs a prompt and performs the prompting. Returns a variant result if the +prompt was completed and not dismissed. The type of result depends on the +action the prompt is completing, and is defined in the Secret Service DBus +API specification. + +If @window_id is non-null then it is used as an XWindow id on Linux. The API +expects this id to be converted to a string using the <literal>%d</literal> +printf format. The Secret Service can make its prompt transient for the window +with this id. In some Secret Service implementations this is not possible, +so the behavior depending on this should degrade gracefully. + +This method may block indefinitely and should not be used in user interface +threads. + + + %NULL if the prompt was dismissed or an error occurred + + + + + a prompt + + + + string form of XWindow id for parent window to be transient for + + + + optional cancellation object + + + + the variant type of the prompt result + + + + + + Runs a prompt and performs the prompting. Returns a variant result if the +prompt was completed and not dismissed. The type of result depends on the +action the prompt is completing, and is defined in the Secret Service DBus +API specification. + +If @window_id is non-null then it is used as an XWindow id on Linux. The API +expects this id to be converted to a string using the <literal>%d</literal> +printf format. The Secret Service can make its prompt transient for the window +with this id. In some Secret Service implementations this is not possible, so +the behavior depending on this should degrade gracefully. + +This runs the dialog in a recursive mainloop. When run from a user interface +thread, this means the user interface will remain responsive. Care should be +taken that appropriate user interface actions are disabled while running the +prompt. + + + %NULL if the prompt was dismissed or an error occurred + + + + + a prompt + + + + string form of XWindow id for parent window to be transient for + + + + optional cancellation object + + + + the variant type of the prompt result + + + + + + + + + + + + + The class for #SecretPrompt. + + + the parent class + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Represents a set of attributes that are stored with an item. These schemas +are used for interoperability between various services storing the same types +of items. + +Each schema has a name like "org.gnome.keyring.NetworkPassword", and defines +a set of attributes, and types (string, integer, boolean) for those attributes. + +Attributes are stored as strings in the Secret Service, and the attribute +types simply define standard ways to store integer and boolean values as strings. +Attributes are represented in libsecret via a #GHashTable with string keys and +values. Even for values that defined as an integer or boolean in the schema, +the attribute values in the #GHashTable are strings. Boolean values are stored +as the strings 'true' and 'false'. Integer values are stored in decimal, with +a preceding negative sign for negative integers. + +Schemas are handled entirely on the client side by this library. The name of the +schema is automatically stored as an attribute on the item. + +Normally when looking up passwords only those with matching schema names are +returned. If the schema @flags contain the %SECRET_SCHEMA_DONT_MATCH_NAME flag, +then lookups will not check that the schema name matches that on the item, only +the schema's attributes are matched. This is useful when you are looking up items +that are not stored by the libsecret library. Other libraries such as libgnome-keyring +don't store the schema name. + + + the dotted name of the schema + + + + flags for the schema + + + + the attribute names and types of those attributes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Using this function is not normally necessary from C code. + +A schema represents a set of attributes that are stored with an item. These +schemas are used for interoperability between various services storing the +same types of items. + +Each schema has an @name like "org.gnome.keyring.NetworkPassword", and +defines a set of attributes names, and types (string, integer, boolean) for +those attributes. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) integers from the +#SecretSchemaAttributeType enumeration, representing the attribute type for +each attribute name. The list of attribtues should be terminated with a %NULL. + +Normally when looking up passwords only those with matching schema names are +returned. If the schema @flags contain the %SECRET_SCHEMA_DONT_MATCH_NAME flag, +then lookups will not check that the schema name matches that on the item, only +the schema's attributes are matched. This is useful when you are looking up items +that are not stored by the libsecret library. Other libraries such as libgnome-keyring +don't store the schema name. + + + the new schema, which should be unreferenced with + secret_schema_unref() when done + + + + + the dotted name of the schema + + + + the flags for the schema + + + + the attribute names and types, terminated with %NULL + + + + + + Using this function is not normally necessary from C code. This is useful +for constructing #SecretSchema structures in bindings. + +A schema represents a set of attributes that are stored with an item. These +schemas are used for interoperability between various services storing the +same types of items. + +Each schema has an @name like "org.gnome.keyring.NetworkPassword", and +defines a set of attributes names, and types (string, integer, boolean) for +those attributes. + +Each key in the @attributes table should be a attribute name strings, and +the values in the table should be integers from the #SecretSchemaAttributeType +enumeration, representing the attribute type for each attribute name. + +Normally when looking up passwords only those with matching schema names are +returned. If the schema @flags contain the %SECRET_SCHEMA_DONT_MATCH_NAME flag, +then lookups will not check that the schema name matches that on the item, only +the schema's attributes are matched. This is useful when you are looking up items +that are not stored by the libsecret library. Other libraries such as libgnome-keyring +don't store the schema name. + + + the new schema, which should be unreferenced with + secret_schema_unref() when done + + + + + the dotted name of the schema + + + + the flags for the schema + + + + the attribute names and types of those attributes + + + + + + + + + Adds a reference to the #SecretSchema. + +It is not normally necessary to call this function from C code, and is +mainly present for the sake of bindings. If the @schema was statically +allocated, then this function will copy the schema. + + + the referenced schema, which should be later + unreferenced with secret_schema_unref() + + + + + the schema to reference + + + + + + Releases a reference to the #SecretSchema. If the last reference is +released then the schema will be freed. + +It is not normally necessary to call this function from C code, and is +mainly present for the sake of bindings. It is an error to call this for +a @schema that was statically allocated. + + + + + + + the schema to reference + + + + + + + An attribute in a #SecretSchema. + + + name of the attribute + + + + the type of the attribute + + + + + The type of an attribute in a #SecretSchema. Attributes are stored as strings +in the Secret Service, and the attribute types simply define standard ways +to store integer and boolean values as strings. + + + a utf-8 string attribute + + + an integer attribute, stored as a decimal + + + a boolean attribute, stored as 'true' or 'false' + + + + Flags for a #SecretSchema definition. + + + no flags for the schema + + + don't match the schema name when looking up or + removing passwords + + + + Different types of schemas for storing secrets, intended for use with +secret_get_schema(). + + + Personal passwords; see %SECRET_SCHEMA_NOTE + + + Network passwords from older + libgnome-keyring storage; see %SECRET_SCHEMA_COMPAT_NETWORK + + + + Various flags to be used with secret_service_search() and secret_service_search_sync(). + + + no flags + + + all the items matching the search will be returned, instead of just the first one + + + unlock locked items while searching + + + while searching load secrets for items that are not locked + + + + A proxy object representing the Secret Service. + + + + + + Disconnect the default #SecretService proxy returned by secret_service_get() +and secret_service_get_sync(). + +It is not necessary to call this function, but you may choose to do so at +program exit. It is useful for testing that memory is not leaked. + +This function is safe to call at any time. But if other objects in this +library are still referenced, then this will not result in all memory +being freed. + + + + + + + Get a #SecretService proxy for the Secret Service. If such a proxy object +already exists, then the same proxy is returned. + +If @flags contains any flags of which parts of the secret service to +ensure are initialized, then those will be initialized before completing. + +This method will return immediately and complete asynchronously. + + + + + + + flags for which service functionality to ensure is initialized + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Complete an asynchronous operation to get a #SecretService proxy for the +Secret Service. + + + a new reference to a #SecretService proxy, which + should be released with g_object_unref(). + + + + + the asynchronous result passed to the callback + + + + + + Get a #SecretService proxy for the Secret Service. If such a proxy object +already exists, then the same proxy is returned. + +If @flags contains any flags of which parts of the secret service to +ensure are initialized, then those will be initialized before returning. + +This method may block indefinitely and should not be used in user interface +threads. + + + a new reference to a #SecretService proxy, which + should be released with g_object_unref(). + + + + + flags for which service functionality to ensure is initialized + + + + optional cancellation object + + + + + + Create a new #SecretService proxy for the Secret Service. + +This function is rarely used, see secret_service_get() instead. + +The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the type +of a derived class. + +If @flags contains any flags of which parts of the secret service to +ensure are initialized, then those will be initialized before returning. + +If @service_bus_name is %NULL then the default is used. + +This method will return immediately and complete asynchronously. + + + + + + + the GType of the new secret service + + + + the D-Bus service name of the secret service + + + + flags for which service functionality to ensure is initialized + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Complete an asynchronous operation to create a new #SecretService proxy for +the Secret Service. + + + a new reference to a #SecretService proxy, which + should be released with g_object_unref(). + + + + + the asynchronous result passed to the callback + + + + + + Create a new #SecretService proxy for the Secret Service. + +This function is rarely used, see secret_service_get_sync() instead. + +The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the +type of a derived class. + +If @flags contains any flags of which parts of the secret service to +ensure are initialized, then those will be initialized before returning. + +If @service_bus_name is %NULL then the default is used. + +This method may block indefinitely and should not be used in user interface +threads. + + + a new reference to a #SecretService proxy, which + should be released with g_object_unref(). + + + + + the GType of the new secret service + + + + the D-Bus service name of the secret service + + + + flags for which service functionality to ensure is initialized + + + + optional cancellation object + + + + + + Get the GObject type for collections instantiated by this service. +This will always be either #SecretCollection or derived from it. + + + the gobject type for collections + + + + + the secret service + + + + + + Get the GObject type for items instantiated by this service. +This will always be either #SecretItem or derived from it. + + + the gobject type for items + + + + + the service + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Complete asynchronous operation to perform prompting for a #SecretPrompt. + +Returns a variant result if the prompt was completed and not dismissed. The +type of result depends on the action the prompt is completing, and is defined +in the Secret Service DBus API specification. + + + %NULL if the prompt was dismissed or an error occurred, + a variant result if the prompt was successful + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Perform prompting for a #SecretPrompt. + +Runs a prompt and performs the prompting. Returns a variant result if the +prompt was completed and not dismissed. The type of result depends on the +action the prompt is completing, and is defined in the Secret Service DBus +API specification. + +This function is called by other parts of this library to handle prompts +for the various actions that can require prompting. + +Override the #SecretServiceClass <literal>prompt_sync</literal> virtual method +to change the behavior of the prompting. The default behavior is to simply +run secret_prompt_perform_sync() on the prompt with a %NULL <literal>window_id</literal>. + + + %NULL if the prompt was dismissed or an error occurred, + a variant result if the prompt was successful + + + + + the secret service + + + + the prompt + + + + optional cancellation object + + + + the variant type of the prompt result + + + + + + Remove unlocked items which match the attributes from the secret service. + +The @attributes should be a set of key and value string pairs. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +This method will return immediately and complete asynchronously. + + + + + + + the secret service + + + + the schema for the attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Finish asynchronous operation to remove items from the secret +service. + + + whether items were removed or not + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Remove unlocked items which match the attributes from the secret service. + +The @attributes should be a set of key and value string pairs. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether items were removed or not + + + + + the secret service + + + + the schema for the attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + + + Create a new collection in the secret service, and return its path. + +Using this method requires that you setup a correct hash table of D-Bus +properties for the new collection. You may prefer to use +secret_collection_create() which does handles this for you. + +An @alias is a well-known tag for a collection, such as 'default' (ie: the +default collection to store items in). This allows other applications to +easily identify and share a collection. If a collection with the @alias +already exists, then instead of creating a new collection, the existing +collection will be returned. If no collection with this alias exists, then a +new collection will be created and this alias will be assigned to it. + +@properties is a set of properties for the new collection. The keys in the +hash table should be interface.property strings like +<literal>org.freedesktop.Secret.Collection.Label</literal>. The values +in the hash table should be #GVariant values of the properties. + +If you wish to have a + +This method will return immediately and complete asynchronously. The secret +service may prompt the user. secret_service_prompt() will be used to handle +any prompts that are required. + + + + + + + a secret service object + + + + hash table of properties for + the new collection + + + + + + + an alias to check for before creating the new + collection, or to assign to the new collection + + + + not currently used + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Finish asynchronous operation to create a new collection in the secret +service. + + + a new string containing the D-Bus object path + of the collection + + + + + a secret service object + + + + the asynchronous result passed to the callback + + + + + + Create a new collection in the secret service and return its path. + +Using this method requires that you setup a correct hash table of D-Bus +properties for the new collection. You may prefer to use +secret_collection_create() which does handles this for you. + +An @alias is a well-known tag for a collection, such as 'default' (ie: the +default collection to store items in). This allows other applications to +easily identify and share a collection. If a collection with the @alias +already exists, then instead of creating a new collection, the existing +collection will be returned. If no collection with this alias exists, then +a new collection will be created and this alias will be assigned to it. + +@properties is a set of properties for the new collection. The keys in the +hash table should be interface.property strings like +<literal>org.freedesktop.Secret.Collection.Label</literal>. The values +in the hash table should be #GVariant values of the properties. + +This method may block indefinitely and should not be used in user interface +threads. The secret service may prompt the user. secret_service_prompt() +will be used to handle any prompts that are required. + + + a new string containing the D-Bus object path + of the collection + + + + + a secret service object + + + + hash table of D-Bus properties + for the new collection + + + + + + + an alias to check for before creating the new + collection, or to assign to the new collection + + + + not currently used + + + + optional cancellation object + + + + + + Create a new item in a secret service collection and return its D-Bus +object path. + +It is often easier to use secret_password_store() or secret_item_create() +rather than using this function. Using this method requires that you setup +a correct hash table of D-Bus @properties for the new collection. + +If the @flags contains %SECRET_ITEM_CREATE_REPLACE, then the secret +service will search for an item matching the @attributes, and update that item +instead of creating a new one. + +@properties is a set of properties for the new collection. The keys in the +hash table should be interface.property strings like +<literal>org.freedesktop.Secret.Item.Label</literal>. The values +in the hash table should be #GVariant values of the properties. + +This method will return immediately and complete asynchronously. The secret +service may prompt the user. secret_service_prompt() will be used to handle +any prompts that are required. + + + + + + + a secret service object + + + + the D-Bus object path of the collection in which to create item + + + + hash table of D-Bus properties + for the new collection + + + + + + + the secret value to store in the item + + + + flags for the creation of the new item + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Finish asynchronous operation to create a new item in the secret +service. + + + a new string containing the D-Bus object path + of the item + + + + + a secret service object + + + + the asynchronous result passed to the callback + + + + + + Create a new item in a secret service collection and return its D-Bus +object path. + +It is often easier to use secret_password_store_sync() or secret_item_create_sync() +rather than using this function. Using this method requires that you setup +a correct hash table of D-Bus @properties for the new collection. + +If the @flags contains %SECRET_ITEM_CREATE_REPLACE, then the secret +service will search for an item matching the @attributes, and update that item +instead of creating a new one. + +@properties is a set of properties for the new collection. The keys in the +hash table should be interface.property strings like +<literal>org.freedesktop.Secret.Item.Label</literal>. The values +in the hash table should be #GVariant values of the properties. + +This method may block indefinitely and should not be used in user interface +threads. The secret service may prompt the user. secret_service_prompt() +will be used to handle any prompts that are required. + + + a new string containing the D-Bus object path + of the item + + + + + a secret service object + + + + the D-Bus path of the collection in which to create item + + + + hash table of D-Bus properties + for the new collection + + + + + + + the secret value to store in the item + + + + flags for the creation of the new item + + + + optional cancellation object + + + + + + Decode a #SecretValue into GVariant received with the Secret Service +DBus API. + +The GVariant should have a <literal>(oayays)</literal> signature. + +A session must have already been established by the #SecretService, and +the encoded secret must be valid for that session. + + + the decoded secret value + + + + + the service + + + + the encoded secret + + + + + + Delete a secret item from the secret service. + +The item is represented by its D-Bus object path. If you already have a +#SecretItem proxy objects, use use secret_item_delete() instead. + +This method will return immediately and complete asynchronously. + + + + + + + the secret service + + + + the D-Bus path of item to delete + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Complete an asynchronous operation to delete a secret item from the secret +service. + + + whether the deletion was successful or not + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Delete a secret item from the secret service. + +The item is represented by its D-Bus object path. If you already have a +#SecretItem proxy objects, use use secret_item_delete_sync() instead. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether the deletion was successful or not + + + + + the secret service + + + + the D-Bus path of item to delete + + + + optional cancellation object + + + + + + Encodes a #SecretValue into GVariant for use with the Secret Service +DBus API. + +The resulting GVariant will have a <literal>(oayays)</literal> signature. + +A session must have already been established by the #SecretService. + + + the encoded secret + + + + + the service + + + + the secret value + + + + + + Ensure that the #SecretService proxy has established a session with the +Secret Service. This session is used to transfer secrets. + +It is not normally necessary to call this method, as the session is +established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION +to secret_service_get() in order to ensure that a session has been established +by the time you get the #SecretService proxy. + +This method will return immediately and complete asynchronously. + + + + + + + the secret service + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Finish an asynchronous operation to ensure that the #SecretService proxy +has established a session with the Secret Service. + + + whether a session is established or not + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Ensure that the #SecretService proxy has established a session with the +Secret Service. This session is used to transfer secrets. + +It is not normally necessary to call this method, as the session is +established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION +to secret_service_get_sync() in order to ensure that a session has been +established by the time you get the #SecretService proxy. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether a session is established or not + + + + + the secret service + + + + optional cancellation object + + + + + + Get the GObject type for collections instantiated by this service. +This will always be either #SecretCollection or derived from it. + + + the gobject type for collections + + + + + the secret service + + + + + + Get a list of #SecretCollection objects representing all the collections +in the secret service. + +If the %SECRET_SERVICE_LOAD_COLLECTIONS flag was not specified when +initializing #SecretService proxy object, then this method will return +%NULL. Use secret_service_load_collections() to load the collections. + + + a + list of the collections in the secret service + + + + + + + the secret service proxy + + + + + + Get the flags representing what features of the #SecretService proxy +have been initialized. + +Use secret_service_ensure_session() or secret_service_load_collections() +to initialize further features and change the flags. + + + the flags for features initialized + + + + + the secret service proxy + + + + + + Get the GObject type for items instantiated by this service. +This will always be either #SecretItem or derived from it. + + + the gobject type for items + + + + + the service + + + + + + Get the secret value for a secret item stored in the service. + +The item is represented by its D-Bus object path. If you already have a +#SecretItem proxy object, use use secret_item_get_secret() to more simply +get its secret value. + +This function returns immediately and completes asynchronously. + + + + + + + the secret service + + + + the D-Bus path to item to retrieve secret for + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to get the secret value for an +secret item stored in the service. + +Will return %NULL if the item is locked. + + + the newly allocated secret value + for the item, which should be released with secret_value_unref() + + + + + the secret service + + + + asynchronous result passed to callback + + + + + + Get the secret value for a secret item stored in the service. + +The item is represented by its D-Bus object path. If you already have a +#SecretItem proxy object, use use secret_item_load_secret_sync() to more simply +get its secret value. + +This method may block indefinitely and should not be used in user interface +threads. + +Will return %NULL if the item is locked. + + + the newly allocated secret value + for the item, which should be released with secret_value_unref() + + + + + the secret service + + + + the D-Bus path to item to retrieve secret for + + + + optional cancellation object + + + + + + Get the secret values for a secret item stored in the service. + +The items are represented by their D-Bus object paths. If you already have +#SecretItem proxy objects, use use secret_item_load_secrets() to more simply +get their secret values. + +This function returns immediately and completes asynchronously. + + + + + + + the secret service + + + + the D-Bus paths to items to retrieve secrets for + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to get the secret values for an +secret items stored in the service. + +Items that are locked will not be included the results. + + + a newly + allocated hash table of item_path keys to #SecretValue + values. + + + + + + + + the secret service + + + + asynchronous result passed to callback + + + + + + Get the secret values for a secret item stored in the service. + +The items are represented by their D-Bus object paths. If you already have +#SecretItem proxy objects, use use secret_item_load_secrets_sync() to more +simply get their secret values. + +This method may block indefinitely and should not be used in user interface +threads. + +Items that are locked will not be included the results. + + + a newly + allocated hash table of item_path keys to #SecretValue + values. + + + + + + + + the secret service + + + + the D-Bus paths to items to retrieve secrets for + + + + optional cancellation object + + + + + + Get the set of algorithms being used to transfer secrets between this +secret service proxy and the Secret Service itself. + +This will be %NULL if no session has been established. Use +secret_service_ensure_session() to establish a session. + + + a string representing the algorithms for transferring + secrets + + + + + the secret service proxy + + + + + + Get the D-Bus object path of the session object being used to transfer +secrets between this secret service proxy and the Secret Service itself. + +This will be %NULL if no session has been established. Use +secret_service_ensure_session() to establish a session. + + + a string representing the D-Bus object path of the + session + + + + + the secret service proxy + + + + + + Ensure that the #SecretService proxy has loaded all the collections present +in the Secret Service. This affects the result of +secret_service_get_collections(). + +You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to +secret_service_get_sync() in order to ensure that the collections have been +loaded by the time you get the #SecretService proxy. + +This method will return immediately and complete asynchronously. + + + + + + + the secret service + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Complete an asynchronous operation to ensure that the #SecretService proxy +has loaded all the collections present in the Secret Service. + + + whether the load was successful or not + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Ensure that the #SecretService proxy has loaded all the collections present +in the Secret Service. This affects the result of +secret_service_get_collections(). + +You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to +secret_service_get_sync() in order to ensure that the collections have been +loaded by the time you get the #SecretService proxy. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether the load was successful or not + + + + + the secret service + + + + optional cancellation object + + + + + + Lock items or collections in the secret service. + +The secret service may not be able to lock items individually, and may +lock an entire collection instead. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +This method returns immediately and completes asynchronously. The secret +service may prompt the user. secret_service_prompt() will be used to handle +any prompts that show up. + + + + + + + the secret service + + + + the items or collections to lock + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Lock items or collections in the secret service. + +The items or collections are represented by their D-Bus object paths. If you +already have #SecretItem and #SecretCollection proxy objects, use use +secret_service_lock() instead. + +The secret service may not be able to lock items individually, and may +lock an entire collection instead. + +This method returns immediately and completes asynchronously. The secret +service may prompt the user. secret_service_prompt() will be used to handle +any prompts that show up. + + + + + + + the secret service + + + + the D-Bus paths for items or collections to lock + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to lock items or collections in the secret +service. + +The secret service may not be able to lock items individually, and may +lock an entire collection instead. + + + the number of items or collections that were locked + + + + + the secret service + + + + asynchronous result passed to the callback + + + + + location to place array of D-Bus paths of items or collections + that were locked + + + + + + + + Lock items or collections in the secret service. + +The items or collections are represented by their D-Bus object paths. If you +already have #SecretItem and #SecretCollection proxy objects, use use +secret_service_lock_sync() instead. + +The secret service may not be able to lock items individually, and may +lock an entire collection instead. + +This method may block indefinitely and should not be used in user +interface threads. The secret service may prompt the user. +secret_service_prompt() will be used to handle any prompts that show up. + + + the number of items or collections that were locked + + + + + the secret service + + + + the D-Bus object paths of the items or collections to lock + + + + optional cancellation object + + + + + location to place array of D-Bus paths of items or collections + that were locked + + + + + + + + Complete asynchronous operation to lock items or collections in the secret +service. + +The secret service may not be able to lock items individually, and may +lock an entire collection instead. + + + the number of items or collections that were locked + + + + + the secret service + + + + asynchronous result passed to the callback + + + + + location to place list of items or collections that were locked + + + + + + + + Lock items or collections in the secret service. + +The secret service may not be able to lock items individually, and may +lock an entire collection instead. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block indefinitely and should not be used in user +interface threads. The secret service may prompt the user. +secret_service_prompt() will be used to handle any prompts that show up. + + + the number of items or collections that were locked + + + + + the secret service + + + + the items or collections to lock + + + + + + optional cancellation object + + + + + location to place list of items or collections that were locked + + + + + + + + Lookup a secret value in the secret service. + +The @attributes should be a set of key and value string pairs. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +This method will return immediately and complete asynchronously. + + + + + + + the secret service + + + + the schema for the attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Finish asynchronous operation to lookup a secret value in the secret service. + +If no secret is found then %NULL is returned. + + + a newly allocated #SecretValue, which should be + released with secret_value_unref(), or %NULL if no secret found + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Lookup a secret value in the secret service. + +The @attributes should be a set of key and value string pairs. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block indefinitely and should not be used in user interface +threads. + + + a newly allocated #SecretValue, which should be + released with secret_value_unref(), or %NULL if no secret found + + + + + the secret service + + + + the schema for the attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + + + Perform prompting for a #SecretPrompt. + +This function is called by other parts of this library to handle prompts +for the various actions that can require prompting. + +Override the #SecretServiceClass <literal>prompt_async</literal> virtual method +to change the behavior of the prompting. The default behavior is to simply +run secret_prompt_perform() on the prompt. + + + + + + + the secret service + + + + the prompt + + + + the variant type of the prompt result + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Perform prompting for a #SecretPrompt. + +This function is called by other parts of this library to handle prompts +for the various actions that can require prompting. + +Override the #SecretServiceClass <literal>prompt_async</literal> virtual method +to change the behavior of the propmting. The default behavior is to simply +run secret_prompt_perform() on the prompt. + + + + + + + the secret service + + + + the D-Bus object path of the prompt + + + + the variant type of the prompt result + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Complete asynchronous operation to perform prompting for a #SecretPrompt. + +Returns a variant result if the prompt was completed and not dismissed. The +type of result depends on the action the prompt is completing, and is defined +in the Secret Service DBus API specification. + + + %NULL if the prompt was dismissed or an + error occurred, a variant result if the prompt was successful + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Perform prompting for a #SecretPrompt. + +Override the #SecretServiceClass <literal>prompt_async</literal> virtual method +to change the behavior of the propmting. The default behavior is to simply +run secret_prompt_perform() on the prompt. + +Returns a variant result if the prompt was completed and not dismissed. The +type of result depends on the action the prompt is completing, and is defined +in the Secret Service DBus API specification. + +This method may block and should not be used in user interface threads. + + + %NULL if the prompt was dismissed or an + error occurred, a variant result if the prompt was successful + + + + + the secret service + + + + the D-Bus object path of the prompt + + + + optional cancellation object + + + + the variant type of the prompt result + + + + + + Complete asynchronous operation to perform prompting for a #SecretPrompt. + +Returns a variant result if the prompt was completed and not dismissed. The +type of result depends on the action the prompt is completing, and is defined +in the Secret Service DBus API specification. + + + %NULL if the prompt was dismissed or an error occurred, + a variant result if the prompt was successful + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Perform prompting for a #SecretPrompt. + +Runs a prompt and performs the prompting. Returns a variant result if the +prompt was completed and not dismissed. The type of result depends on the +action the prompt is completing, and is defined in the Secret Service DBus +API specification. + +This function is called by other parts of this library to handle prompts +for the various actions that can require prompting. + +Override the #SecretServiceClass <literal>prompt_sync</literal> virtual method +to change the behavior of the prompting. The default behavior is to simply +run secret_prompt_perform_sync() on the prompt with a %NULL <literal>window_id</literal>. + + + %NULL if the prompt was dismissed or an error occurred, + a variant result if the prompt was successful + + + + + the secret service + + + + the prompt + + + + optional cancellation object + + + + the variant type of the prompt result + + + + + + Lookup which collection is assigned to this alias. Aliases help determine +well known collections, such as 'default'. This method looks up the +dbus object path of the well known collection. + +This method will return immediately and complete asynchronously. + + + + + + + a secret service object + + + + the alias to lookup + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Finish an asynchronous operation to lookup which collection is assigned +to an alias. This method returns the DBus object path of the collection + + + the collection dbus object path, + or %NULL if none assigned to the alias + + + + + a secret service object + + + + asynchronous result passed to callback + + + + + + Lookup which collection is assigned to this alias. Aliases help determine +well known collections, such as 'default'. This method returns the dbus +object path of the collection. + +This method may block and should not be used in user interface threads. + + + the collection dbus object path, + or %NULL if none assigned to the alias + + + + + a secret service object + + + + the alias to lookup + + + + optional cancellation object + + + + + + Search for items matching the @attributes. All collections are searched. +The @attributes should be a table of string keys and string values. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the +search will be returned. Otherwise only the first item will be returned. +This is almost always the unlocked item that was most recently stored. + +If %SECRET_SEARCH_UNLOCK is set in @flags, then items will be unlocked +if necessary. In either case, locked and unlocked items will match the +search and be returned. If the unlock fails, the search does not fail. + +If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have +their secret values loaded and available via secret_item_get_secret(). + +This function returns immediately and completes asynchronously. + + + + + + + the secret service + + + + the schema for the attributes + + + + search for items matching these attributes + + + + + + + search option flags + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to search for items. + + + + a list of items that matched the search + + + + + + + the secret service + + + + asynchronous result passed to callback + + + + + + Search for items matching the @attributes, and return their D-Bus object paths. +All collections are searched. The @attributes should be a table of string keys +and string values. + +This function returns immediately and completes asynchronously. + +When your callback is called use secret_service_search_for_dbus_paths_finish() +to get the results of this function. Only the D-Bus object paths of the +items will be returned. If you would like #SecretItem objects to be returned +instead, then use the secret_service_search() function. + + + + + + + the secret service + + + + the schema for the attributes + + + + search for items matching these attributes + + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to search for items, and return their +D-Bus object paths. + +Matching items that are locked or unlocked, have their D-Bus paths placed +in the @locked or @unlocked arrays respectively. + +D-Bus object paths of the items will be returned in the @unlocked or +@locked arrays. If you would to have #SecretItem objects to be returned +instead, then us the secret_service_search() and +secret_service_search_finish() functions. + + + whether the search was successful or not + + + + + the secret service + + + + asynchronous result passed to callback + + + + + location to place an array of D-Bus object paths for matching + items which were locked. + + + + + + + location to place an array of D-Bus object paths for matching + items which were locked. + + + + + + + + Search for items matching the @attributes, and return their D-Bus object +paths. All collections are searched. The @attributes should be a table of +string keys and string values. + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + +Matching items that are locked or unlocked, have their D-Bus paths placed +in the @locked or @unlocked arrays respectively. + +D-Bus object paths of the items will be returned in the @unlocked or +@locked arrays. If you would to have #SecretItem objects to be returned +instead, then use the secret_service_search_sync() function. + + + whether the search was successful or not + + + + + the secret service + + + + the schema for the attributes + + + + search for items matching these attributes + + + + + + + optional cancellation object + + + + + location to place an array of D-Bus object paths for matching + items which were locked. + + + + + + + location to place an array of D-Bus object paths for matching + items which were locked. + + + + + + + + Search for items matching the @attributes. All collections are searched. +The @attributes should be a table of string keys and string values. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the +search will be returned. Otherwise only the first item will be returned. +This is almost always the unlocked item that was most recently stored. + +If %SECRET_SEARCH_UNLOCK is set in @flags, then items will be unlocked +if necessary. In either case, locked and unlocked items will match the +search and be returned. If the unlock fails, the search does not fail. + +If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items' secret +values will be loaded for any unlocked items. Loaded item secret values +are available via secret_item_get_secret(). If the load of a secret values +fail, then the + +This function may block indefinitely. Use the asynchronous version +in user interface threads. + + + + a list of items that matched the search + + + + + + + the secret service + + + + the schema for the attributes + + + + search for items matching these attributes + + + + + + + search option flags + + + + optional cancellation object + + + + + + Assign a collection to this alias. Aliases help determine +well known collections, such as 'default'. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +This method will return immediately and complete asynchronously. + + + + + + + a secret service object + + + + the alias to assign the collection to + + + + the collection to assign to the alias + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Finish an asynchronous operation to assign a collection to an alias. + + + %TRUE if successful + + + + + a secret service object + + + + asynchronous result passed to callback + + + + + + Assign a collection to this alias. Aliases help determine +well known collections, such as 'default'. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block and should not be used in user interface threads. + + + %TRUE if successful + + + + + a secret service object + + + + the alias to assign the collection to + + + + the collection to assign to the alias + + + + optional cancellation object + + + + + + Assign a collection to this alias. Aliases help determine +well known collections, such as 'default'. This method takes the dbus object +path of the collection to assign to the alias. + +This method will return immediately and complete asynchronously. + + + + + + + a secret service object + + + + the alias to assign the collection to + + + + the dbus object path of the collection to assign to the alias + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Finish an asynchronous operation to assign a collection to an alias. + + + %TRUE if successful + + + + + a secret service object + + + + asynchronous result passed to callback + + + + + + Assign a collection to this alias. Aliases help determine +well known collections, such as 'default'. This method takes the dbus object +path of the collection to assign to the alias. + +This method may block and should not be used in user interface threads. + + + %TRUE if successful + + + + + a secret service object + + + + the alias to assign the collection to + + + + the dbus object path of the collection to assign to the alias + + + + optional cancellation object + + + + + + Store a secret value in the secret service. + +The @attributes should be a set of key and value string pairs. + +If the attributes match a secret item already stored in the collection, then +the item will be updated with these new values. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +If @collection is not specified, then the default collection will be +used. Use #SECRET_COLLECTION_SESSION to store the password in the session +collection, which doesn't get stored across login sessions. + +This method will return immediately and complete asynchronously. + + + + + + + the secret service + + + + the schema to use to check attributes + + + + the attribute keys and values + + + + + + + a collection alias, or D-Bus object path of the collection where to store the secret + + + + label for the secret + + + + the secret value + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Finish asynchronous operation to store a secret value in the secret service. + + + whether the storage was successful or not + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + Store a secret value in the secret service. + +The @attributes should be a set of key and value string pairs. + +If the attributes match a secret item already stored in the collection, then +the item will be updated with these new values. + +If @collection is %NULL, then the default collection will be +used. Use #SECRET_COLLECTION_SESSION to store the password in the session +collection, which doesn't get stored across login sessions. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether the storage was successful or not + + + + + the secret service + + + + the schema for the attributes + + + + the attribute keys and values + + + + + + + a collection alias, or D-Bus object path of the collection where to store the secret + + + + label for the secret + + + + the secret value + + + + optional cancellation object + + + + + + Unlock items or collections in the secret service. + +The secret service may not be able to unlock items individually, and may +unlock an entire collection instead. + +If @service is NULL, then secret_service_get() will be called to get +the default #SecretService proxy. + +This method may block indefinitely and should not be used in user +interface threads. The secret service may prompt the user. +secret_service_prompt() will be used to handle any prompts that show up. + + + + + + + the secret service + + + + the items or collections to unlock + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Unlock items or collections in the secret service. + +The items or collections are represented by their D-Bus object paths. If you +already have #SecretItem and #SecretCollection proxy objects, use use +secret_service_unlock() instead. + +The secret service may not be able to unlock items individually, and may +unlock an entire collection instead. + +This method returns immediately and completes asynchronously. The secret +service may prompt the user. secret_service_prompt() will be used to handle +any prompts that show up. + + + + + + + the secret service + + + + the D-Bus paths for items or collections to unlock + + + + optional cancellation object + + + + called when the operation completes + + + + data to pass to the callback + + + + + + Complete asynchronous operation to unlock items or collections in the secret +service. + +The secret service may not be able to unlock items individually, and may +unlock an entire collection instead. + + + the number of items or collections that were unlocked + + + + + the secret service + + + + asynchronous result passed to the callback + + + + + location to place array of D-Bus paths of items or collections + that were unlocked + + + + + + + + Unlock items or collections in the secret service. + +The items or collections are represented by their D-Bus object paths. If you +already have #SecretItem and #SecretCollection proxy objects, use use +secret_service_unlock_sync() instead. + +The secret service may not be able to unlock items individually, and may +unlock an entire collection instead. + +This method may block indefinitely and should not be used in user +interface threads. The secret service may prompt the user. +secret_service_prompt() will be used to handle any prompts that show up. + + + the number of items or collections that were unlocked + + + + + the secret service + + + + the D-Bus object paths of the items or collections to unlock + + + + optional cancellation object + + + + + location to place array of D-Bus paths of items or collections + that were unlocked + + + + + + + + Complete asynchronous operation to unlock items or collections in the secret +service. + +The secret service may not be able to unlock items individually, and may +unlock an entire collection instead. + + + the number of items or collections that were unlocked + + + + + the secret service + + + + asynchronous result passed to the callback + + + + + location to place list of items or collections that were unlocked + + + + + + + + Unlock items or collections in the secret service. + +The secret service may not be able to unlock items individually, and may +unlock an entire collection instead. + +If @service is NULL, then secret_service_get_sync() will be called to get +the default #SecretService proxy. + +This method may block indefinitely and should not be used in user +interface threads. The secret service may prompt the user. +secret_service_prompt() will be used to handle any prompts that show up. + + + the number of items or collections that were unlocked + + + + + the secret service + + + + the items or collections to unlock + + + + + + optional cancellation object + + + + + location to place list of items or collections that were unlocked + + + + + + + + A list of #SecretCollection objects representing the collections in +the Secret Service. This list may be %NULL if the collections have +not been loaded. + +To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS +initialization flag when calling the secret_service_get() or +secret_service_open() functions. Or call the secret_service_load_collections() +method. + + + + A set of flags describing which parts of the secret service have +been initialized. + + + + + + + + + + + The class for #SecretService. + + + the parent class + + + + the #GType of the #SecretCollection objects instantiated + by the #SecretService proxy + + + + the #GType of the #SecretItem objects instantiated by the + #SecretService proxy + + + + + + + %NULL if the prompt was dismissed or an error occurred, + a variant result if the prompt was successful + + + + + the secret service + + + + the prompt + + + + optional cancellation object + + + + the variant type of the prompt result + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %NULL if the prompt was dismissed or an error occurred, + a variant result if the prompt was successful + + + + + the secret service + + + + the asynchronous result passed to the callback + + + + + + + + + + the gobject type for collections + + + + + the secret service + + + + + + + + + + the gobject type for items + + + + + the service + + + + + + + + + + + + + Flags which determine which parts of the #SecretService proxy are initialized +during a secret_service_get() or secret_service_open() operation. + + + no flags for initializing the #SecretService + + + establish a session for transfer of secrets + while initializing the #SecretService + + + load collections while initializing the + #SecretService + + + + + + + A secret value, like a password or other binary secret. + + + Create a #SecretValue for the secret data passed in. The secret data is +copied into non-pageable 'secure' memory. + +If the length is less than zero, then @secret is assumed to be +null-terminated. + + + the new #SecretValue + + + + + the secret data + + + + the length of the data + + + + the content type of the data + + + + + + Create a #SecretValue for the secret data passed in. The secret data is +not copied, and will later be freed with the @destroy function. + +If the length is less than zero, then @secret is assumed to be +null-terminated. + + + the new #SecretValue + + + + + the secret data + + + + the length of the data + + + + the content type of the data + + + + function to call to free the secret data + + + + + + Get the secret data in the #SecretValue. The value is not necessarily +null-terminated unless it was created with secret_value_new() or a +null-terminated string was passed to secret_value_new_full(). + + + the secret data + + + + + + + the value + + + + the length of the secret + + + + + + Get the content type of the secret value, such as +<literal>text/plain</literal>. + + + the content type + + + + + the value + + + + + + Get the secret data in the #SecretValue if it contains a textual +value. The content type must be <literal>text/plain</literal>. + + + the content type + + + + + the value + + + + + + Add another reference to the #SecretValue. For each reference +secret_value_unref() should be called to unreference the value. + + + the value + + + + + value to reference + + + + + + Unreference a #SecretValue. When the last reference is gone, then +the value will be freed. + + + + + + + value to unreference + + + + + + + Build up a hash table of attribute values. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the password +@schema. The list of attribtues should be terminated with a %NULL. + + + a new table of + attributes, to be released with g_hash_table_unref() + + + + + + + + the schema for the attributes + + + + the attribute keys and values, terminated with %NULL + + + + + + Build up a hash table of attribute values. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the password +@schema. The list of attribtues should be terminated with a %NULL. + + + a new table of + attributes, to be released with g_hash_table_unref() + + + + + + + + the schema for the attributes + + + + the attribute keys and values, terminated with %NULL + + + + + + + + + + + + Get a secret storage schema of the given @type. + +C code may access the schemas (such as %SECRET_SCHEMA_NOTE) directly, but +language bindings cannot, and must use this accessor. + + + schema type + + + + + type of schema to get + + + + + + Clear unlocked matching passwords from the secret service. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the password +@schema. The list of attribtues should be terminated with a %NULL. + +All unlocked items that match the attributes will be deleted. + +This method will return immediately and complete asynchronously. + + + + + + + the schema for the attributes + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + the attribute keys and values, terminated with %NULL + + + + + + Finish an asynchronous operation to remove passwords from the secret +service. + + + whether any passwords were removed + + + + + the asynchronous result passed to the callback + + + + + + Remove unlocked matching passwords from the secret service. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the password +@schema. The list of attribtues should be terminated with a %NULL. + +All unlocked items that match the attributes will be deleted. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether the any passwords were removed + + + + + the schema for the attributes + + + + optional cancellation object + + + + location to place an error on failure + + + + the attribute keys and values, terminated with %NULL + + + + + + Remove unlocked matching passwords from the secret service. + +The @attributes should be a set of key and value string pairs. + +All unlocked items that match the attributes will be deleted. + +This method will return immediately and complete asynchronously. + + + + + + + the schema for the attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Remove unlocked matching passwords from the secret service. + +The @attributes should be a set of key and value string pairs. + +All unlocked items that match the attributes will be deleted. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether any passwords were removed + + + + + the schema for the attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + + + Clear the memory used by a password, and then free it. + +This function must be used to free nonpageable memory returned by +secret_password_lookup_nonpageable_finish(), +secret_password_lookup_nonpageable_sync() or +secret_password_lookupv_nonpageable_sync(). + + + + + + + password to free + + + + + + Lookup a password in the secret service. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the password +@schema. The list of attribtues should be terminated with a %NULL. + +If no secret is found then %NULL is returned. + +This method will return immediately and complete asynchronously. + + + + + + + the schema for the attributes + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + the attribute keys and values, terminated with %NULL + + + + + + Finish an asynchronous operation to lookup a password in the secret service. + + + a new password string which should be freed with + secret_password_free() or may be freed with g_free() when done + + + + + the asynchronous result passed to the callback + + + + + + Finish an asynchronous operation to lookup a password in the secret service. + + + a new password string stored in nonpageable memory + which must be freed with secret_password_free() when done + + + + + the asynchronous result passed to the callback + + + + + + Lookup a password in the secret service. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the password +@schema. The list of attribtues should be terminated with a %NULL. + +If no secret is found then %NULL is returned. + +This method may block indefinitely and should not be used in user interface +threads. + + + a new password string stored in nonpageable memory + which must be freed with secret_password_free() when done + + + + + the schema for the attributes + + + + optional cancellation object + + + + location to place an error on failure + + + + the attribute keys and values, terminated with %NULL + + + + + + Lookup a password in the secret service. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the password +@schema. The list of attributes should be terminated with a %NULL. + +If no secret is found then %NULL is returned. + +This method may block indefinitely and should not be used in user interface +threads. + + + a new password string which should be freed with + secret_password_free() or may be freed with g_free() when done + + + + + the schema for the attributes + + + + optional cancellation object + + + + location to place an error on failure + + + + the attribute keys and values, terminated with %NULL + + + + + + Lookup a password in the secret service. + +The @attributes should be a set of key and value string pairs. + +If no secret is found then %NULL is returned. + +This method will return immediately and complete asynchronously. + + + + + + + the schema for attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Lookup a password in the secret service. + +The @attributes should be a set of key and value string pairs. + +If no secret is found then %NULL is returned. + +This method may block indefinitely and should not be used in user interface +threads. + + + a new password string stored in non pageable memory + which should be freed with secret_password_free() when done + + + + + the schema for attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + + + Lookup a password in the secret service. + +The @attributes should be a set of key and value string pairs. + +If no secret is found then %NULL is returned. + +This method may block indefinitely and should not be used in user interface +threads. + + + a new password string which should be freed with + secret_password_free() or may be freed with g_free() when done + + + + + the schema for attributes + + + + the attribute keys and values + + + + + + + optional cancellation object + + + + + + Store a password in the secret service. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the @schema. +The list of attribtues should be terminated with a %NULL. + +If the attributes match a secret item already stored in the collection, then +the item will be updated with these new values. + +If @collection is %NULL, then the default collection will be +used. Use #SECRET_COLLECTION_SESSION to store the password in the session +collection, which doesn't get stored across login sessions. + +This method will return immediately and complete asynchronously. + + + + + + + the schema for attributes + + + + a collection alias, or D-Bus object path of the collection where to store the secret + + + + label for the secret + + + + the null-terminated password to store + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + the attribute keys and values, terminated with %NULL + + + + + + Finish asynchronous operation to store a password in the secret service. + + + whether the storage was successful or not + + + + + the asynchronous result passed to the callback + + + + + + Store a password in the secret service. + +The variable argument list should contain pairs of a) The attribute name as +a null-terminated string, followed by b) attribute value, either a character +string, an int number, or a gboolean value, as defined in the @schema. +The list of attribtues should be terminated with a %NULL. + +If the attributes match a secret item already stored in the collection, then +the item will be updated with these new values. + +If @collection is %NULL, then the default collection will be +used. Use #SECRET_COLLECTION_SESSION to store the password in the session +collection, which doesn't get stored across login sessions. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether the storage was successful or not + + + + + the schema for attributes + + + + a collection alias, or D-Bus object path of the collection where to store the secret + + + + label for the secret + + + + the null-terminated password to store + + + + optional cancellation object + + + + location to place an error on failure + + + + the attribute keys and values, terminated with %NULL + + + + + + Store a password in the secret service. + +The @attributes should be a set of key and value string pairs. + +If the attributes match a secret item already stored in the collection, then +the item will be updated with these new values. + +If @collection is %NULL, then the default collection will be +used. Use #SECRET_COLLECTION_SESSION to store the password in the session +collection, which doesn't get stored across login sessions. + +This method will return immediately and complete asynchronously. + + + + + + + the schema for attributes + + + + the attribute keys and values + + + + + + + a collection alias, or D-Bus object path of the collection where to store the secret + + + + label for the secret + + + + the null-terminated password to store + + + + optional cancellation object + + + + called when the operation completes + + + + data to be passed to the callback + + + + + + Store a password in the secret service. + +The @attributes should be a set of key and value string pairs. + +If the attributes match a secret item already stored in the collection, then +the item will be updated with these new values. + +If @collection is %NULL, then the default collection will be +used. Use #SECRET_COLLECTION_SESSION to store the password in the session +collection, which doesn't get stored across login sessions. + +This method may block indefinitely and should not be used in user interface +threads. + + + whether the storage was successful or not + + + + + the schema for attributes + + + + the attribute keys and values + + + + + + + a collection alias, or D-Bus object path of the collection where to store the secret + + + + label for the secret + + + + the null-terminated password to store + + + + optional cancellation object + + + + + + Clear the memory used by a password. + + + + + + + password to clear + + + + + + diff --git a/gir-files/Soup-2.4.gir b/gir-files/Soup-2.4.gir new file mode 100644 index 0000000..a58f462 --- /dev/null +++ b/gir-files/Soup-2.4.gir @@ -0,0 +1,21216 @@ + + + + + + + + + + + + + + + + This can be passed to any #SoupAddress method that expects a port, +to indicate that you don't care what port is used. + + + + + + + + + + + + Alias for the #SoupAddress:family property. (The +#SoupAddressFamily for this address.) + + + + + + + + + + + + Alias for the #SoupAddress:name property. (The hostname for +this address.) + + + + + An alias for the #SoupAddress:physical property. (The +stringified IP address for this address.) + + + + + An alias for the #SoupAddress:port property. (The port for +this address.) + + + + + Alias for the #SoupAddress:protocol property. (The URI scheme +used with this address.) + + + + + An alias for the #SoupAddress:sockaddr property. (A pointer +to the struct sockaddr for this address.) + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupAuthDomain:add-path property. (Shortcut +for calling soup_auth_domain_add_path().) + + + + + + + + + + + + Alias for the #SoupAuthDomainBasic:auth-callback property. +(The #SoupAuthDomainBasicAuthCallback.) + + + + + Alias for the #SoupAuthDomainBasic:auth-data property. +(The data to pass to the #SoupAuthDomainBasicAuthCallback.) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupAuthDomainDigest:auth-callback property. +(The #SoupAuthDomainDigestAuthCallback.) + + + + + Alias for the #SoupAuthDomainDigest:auth-callback property. +(The #SoupAuthDomainDigestAuthCallback.) + + + + + + + + + + + + + + + + + + + Alias for the #SoupAuthDomain:filter property. (The +#SoupAuthDomainFilter for the domain.) + + + + + Alias for the #SoupAuthDomain:filter-data property. (Data +to pass to the #SoupAuthDomainFilter.) + + + + + Alias for the #SoupAuthDomain:generic-auth-callback property. +(The #SoupAuthDomainGenericAuthCallback.) + + + + + Alias for the #SoupAuthDomain:generic-auth-data property. +(The data to pass to the #SoupAuthDomainGenericAuthCallback.) + + + + + + + + + + + + Alias for the #SoupAuthDomain:proxy property. (Whether or +not this is a proxy auth domain.) + + + + + Alias for the #SoupAuthDomain:realm property. (The realm of +this auth domain.) + + + + + Alias for the #SoupAuthDomain:remove-path property. +(Shortcut for calling soup_auth_domain_remove_path().) + + + + + + + + + + + + An alias for the #SoupAuth:host property. (The +host being authenticated to.) + + + + + An alias for the #SoupAuth:is-authenticated property. +(Whether or not the auth has been authenticated.) + + + + + An alias for the #SoupAuth:is-for-proxy property. (Whether +or not the auth is for a proxy server.) + + + + + + + + + + + + + + + + + + + + + + + + + + An alias for the #SoupAuth:realm property. (The +authentication realm.) + + + + + An alias for the #SoupAuth:scheme-name property. (The +authentication scheme name.) + + + + + + + + Creates a #SoupAddress from @name and @port. The #SoupAddress's IP +address may not be available right away; the caller can call +soup_address_resolve_async() or soup_address_resolve_sync() to +force a DNS resolution. + + + a #SoupAddress + + + + + a hostname or physical address + + + + a port number + + + + + + Returns a #SoupAddress corresponding to the "any" address +for @family (or %NULL if @family isn't supported), suitable for +using as a listening #SoupSocket. + + + the new #SoupAddress + + + + + the address family + + + + the port number (usually %SOUP_ADDRESS_ANY_PORT) + + + + + + Returns a #SoupAddress equivalent to @sa (or %NULL if @sa's +address family isn't supported) + + + the new #SoupAddress + + + + + a pointer to a sockaddr + + + + size of @sa + + + + + + Tests if @addr1 and @addr2 have the same IP address. This method +can be used with soup_address_hash_by_ip() to create a +#GHashTable that hashes on IP address. + +This would be used to distinguish hosts in situations where +different virtual hosts on the same IP address should be considered +the same. Eg, if "www.example.com" and "www.example.net" have the +same IP address, then a single connection can be used to talk +to either of them. + +See also soup_address_equal_by_name(), which compares by name +rather than by IP address. + + + whether or not @addr1 and @addr2 have the same IP +address. + + + + + a #SoupAddress with a resolved IP + address + + + + another #SoupAddress with a resolved + IP address + + + + + + Tests if @addr1 and @addr2 have the same "name". This method can be +used with soup_address_hash_by_name() to create a #GHashTable that +hashes on address "names". + +Comparing by name normally means comparing the addresses by their +hostnames. But if the address was originally created using an IP +address literal, then it will be compared by that instead. + +In particular, if "www.example.com" has the IP address 10.0.0.1, +and @addr1 was created with the name "www.example.com" and @addr2 +was created with the name "10.0.0.1", then they will compare as +unequal for purposes of soup_address_equal_by_name(). + +This would be used to distinguish hosts in situations where +different virtual hosts on the same IP address should be considered +different. Eg, for purposes of HTTP authentication or cookies, two +hosts with the same IP address but different names are considered +to be different hosts. + +See also soup_address_equal_by_ip(), which compares by IP address +rather than by name. + + + whether or not @addr1 and @addr2 have the same name + + + + + a #SoupAddress with a resolved name + + + + another #SoupAddress with a resolved + name + + + + + + Creates a new #GSocketAddress corresponding to @addr (which is assumed +to only have one socket address associated with it). + + + a new #GSocketAddress + + + + + a #SoupAddress + + + + + + Returns the hostname associated with @addr. + +This method is not thread-safe; if you call it while @addr is being +resolved in another thread, it may return garbage. You can use +soup_address_is_resolved() to safely test whether or not an address +is resolved before fetching its name or address. + + + the hostname, or %NULL if it is not known. + + + + + a #SoupAddress + + + + + + Returns the physical address associated with @addr as a string. +(Eg, "127.0.0.1"). If the address is not yet known, returns %NULL. + +This method is not thread-safe; if you call it while @addr is being +resolved in another thread, it may return garbage. You can use +soup_address_is_resolved() to safely test whether or not an address +is resolved before fetching its name or address. + + + the physical address, or %NULL + + + + + a #SoupAddress + + + + + + Returns the port associated with @addr. + + + the port + + + + + a #SoupAddress + + + + + + Returns the sockaddr associated with @addr, with its length in +*@len. If the sockaddr is not yet known, returns %NULL. + +This method is not thread-safe; if you call it while @addr is being +resolved in another thread, it may return garbage. You can use +soup_address_is_resolved() to safely test whether or not an address +is resolved before fetching its name or address. + + + the sockaddr, or %NULL + + + + + a #SoupAddress + + + + return location for sockaddr length + + + + + + A hash function (for #GHashTable) that corresponds to +soup_address_equal_by_ip(), qv + + + the IP-based hash value for @addr. + + + + + a #SoupAddress + + + + + + A hash function (for #GHashTable) that corresponds to +soup_address_equal_by_name(), qv + + + the named-based hash value for @addr. + + + + + a #SoupAddress + + + + + + Tests if @addr has already been resolved. Unlike the other +#SoupAddress "get" methods, this is safe to call when @addr might +be being resolved in another thread. + + + %TRUE if @addr has been resolved. + + + + + a #SoupAddress + + + + + + Asynchronously resolves the missing half of @addr (its IP address +if it was created with soup_address_new(), or its hostname if it +was created with soup_address_new_from_sockaddr() or +soup_address_new_any().) + +If @cancellable is non-%NULL, it can be used to cancel the +resolution. @callback will still be invoked in this case, with a +status of %SOUP_STATUS_CANCELLED. + +It is safe to call this more than once on a given address, from the +same thread, with the same @async_context (and doing so will not +result in redundant DNS queries being made). But it is not safe to +call from multiple threads, or with different @async_contexts, or +mixed with calls to soup_address_resolve_sync(). + + + + + + + a #SoupAddress + + + + the #GMainContext to call @callback from + + + + a #GCancellable object, or %NULL + + + + callback to call with the result + + + + data for @callback + + + + + + Synchronously resolves the missing half of @addr, as with +soup_address_resolve_async(). + +If @cancellable is non-%NULL, it can be used to cancel the +resolution. soup_address_resolve_sync() will then return a status +of %SOUP_STATUS_CANCELLED. + +It is safe to call this more than once, even from different +threads, but it is not safe to mix calls to +soup_address_resolve_sync() with calls to +soup_address_resolve_async() on the same address. + + + %SOUP_STATUS_OK, %SOUP_STATUS_CANT_RESOLVE, or +%SOUP_STATUS_CANCELLED. + + + + + a #SoupAddress + + + + a #GCancellable object, or %NULL + + + + + + + + + + + + + + + + + + + + + + + + + + + + The callback function passed to soup_address_resolve_async(). + + + + + + + the #SoupAddress that was resolved + + + + %SOUP_STATUS_OK, %SOUP_STATUS_CANT_RESOLVE, or +%SOUP_STATUS_CANCELLED + + + + the user data that was passed to +soup_address_resolve_async() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The supported address families. + + an invalid %SoupAddress + + + an IPv4 address + + + an IPv6 address + + + + 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. + + + Creates a new #SoupAuth of type @type with the information from +@msg and @auth_header. + +This is called by #SoupSession; you will normally not create auths +yourself. + + + the new #SoupAuth, or %NULL if it could +not be created + + + + + the type of auth to create (a subtype of #SoupAuth) + + + + 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 +soup_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 soup_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 soup_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 soup_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 soup_auth_new(), this is +normally only used by #SoupSession. + + + %TRUE if @auth is still a valid (but potentially +unauthenticated) #SoupAuth. %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 +soup_auth_authenticate(). + + + %TRUE if @auth is able to accept credentials. + + + + + a #SoupAuth + + + + + + Frees @space. + + + + + + + a #SoupAuth + + + + the return value from soup_auth_get_protection_space() + + + + + + + + Generates an appropriate "Authorization" header for @msg. (The +session will only call this if soup_auth_is_authenticated() +returned %TRUE.) + + + the "Authorization" header, which must be freed. + + + + + a #SoupAuth + + + + the #SoupMessage to be authorized + + + + + + Returns the host that @auth is associated with. + + + the hostname + + + + + a #SoupAuth + + + + + + Gets an opaque identifier for @auth, for use as a hash key or the +like. #SoupAuth 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 soup_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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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 soup_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 soup_auth_new(), this is +normally only used by #SoupSession. + + + %TRUE if @auth is still a valid (but potentially +unauthenticated) #SoupAuth. %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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %TRUE if @auth is still a valid (but potentially +unauthenticated) #SoupAuth. %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 soup_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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to @msg, +requesting that the client authenticate, and sets @msg's status +accordingly. + +This is used by #SoupServer internally and is probably of no use to +anyone else. + + + + + + + a #SoupAuthDomain + + + + a #SoupMessage + + + + + + Checks if @msg authenticates to @domain via @username and +@password. This would normally be called from a +#SoupAuthDomainGenericAuthCallback. + + + whether or not the message is authenticated + + + + + a #SoupAuthDomain + + + + a #SoupMessage + + + + a username + + + + a password + + + + + + Checks if @msg contains appropriate authorization for @domain to +accept it. Mirroring soup_auth_domain_covers(), this does not check +whether or not @domain <emphasis>cares</emphasis> if @msg is +authorized. + +This is used by #SoupServer 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 #SoupMessage + + + + + + Adds @path to @domain, such that requests under @path on @domain's +server will require authentication (unless overridden by +soup_auth_domain_remove_path() or soup_auth_domain_set_filter()). + +You can also add paths by setting the %SOUP_AUTH_DOMAIN_ADD_PATH +property, which can also be used to add one or more paths at +construct time. + + + + + + + a #SoupAuthDomain + + + + the path to add to @domain + + + + + + Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to @msg, +requesting that the client authenticate, and sets @msg's status +accordingly. + +This is used by #SoupServer internally and is probably of no use to +anyone else. + + + + + + + a #SoupAuthDomain + + + + a #SoupMessage + + + + + + Checks if @msg authenticates to @domain via @username and +@password. This would normally be called from a +#SoupAuthDomainGenericAuthCallback. + + + whether or not the message is authenticated + + + + + a #SoupAuthDomain + + + + a #SoupMessage + + + + 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 <emphasis>is</emphasis> authenticated, merely whether +or not it needs to be. + +This is used by #SoupServer internally and is probably of no use to +anyone else. + + + %TRUE if @domain requires @msg to be authenticated + + + + + a #SoupAuthDomain + + + + a #SoupMessage + + + + + + Gets the realm name associated with @domain + + + @domain's realm + + + + + a #SoupAuthDomain + + + + + + Removes @path from @domain, such that requests under @path on +@domain's server will NOT require authentication. + +This is not simply an undo-er for soup_auth_domain_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 soup_auth_domain_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. + +You can also remove paths by setting the +%SOUP_AUTH_DOMAIN_REMOVE_PATH property, which can also be used to +remove one or more paths at construct time. + + + + + + + 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 %SOUP_AUTH_DOMAIN_FILTER +and %SOUP_AUTH_DOMAIN_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, +#SoupAuthDomainDigestAuthCallback), the generic auth callback +will be invoked. See #SoupAuthDomainGenericAuthCallback 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 #SoupAuthDomainFilter for the domain + + + + + + + The #SoupAuthDomainGenericAuthCallback for the domain + + + + + + + + + + + + + + + + + + + + + + Creates a #SoupAuthDomainBasic. You must set the +%SOUP_AUTH_DOMAIN_REALM parameter, 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 +%SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK and +%SOUP_AUTH_DOMAIN_BASIC_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 #SoupAuthDomainBasicAuthCallback + + + + The data to pass to the #SoupAuthDomainBasicAuthCallback + + + + + + + + Callback used by #SoupAuthDomainBasic 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 soup_auth_domain_basic_set_auth_callback() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #SoupAuthDomain + + + + a #SoupMessage + + + + + + + + + + whether or not the message is authenticated + + + + + a #SoupAuthDomain + + + + a #SoupMessage + + + + a username + + + + a password + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a #SoupAuthDomainDigest. You must set the +%SOUP_AUTH_DOMAIN_REALM parameter, 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 +#SoupAuthDomainDigest'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 +%SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK and +%SOUP_AUTH_DOMAIN_DIGEST_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 #SoupAuthDomainDigestAuthCallback + + + + The data to pass to the #SoupAuthDomainDigestAuthCallback + + + + + + + + Callback used by #SoupAuthDomainDigest for authentication purposes. +The application should look up @username in its password database, +and return the corresponding encoded password (see +soup_auth_domain_digest_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 soup_auth_domain_digest_set_auth_callback() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The prototype for a #SoupAuthDomain filter; see +soup_auth_domain_set_filter() for details. + + + %TRUE if @msg requires authentication, %FALSE if not. + + + + + a #SoupAuthDomain + + + + a #SoupMessage + + + + the data passed to soup_auth_domain_set_filter() + + + + + + The prototype for a #SoupAuthDomain generic authentication callback. + +The callback should look up the user's password, call +soup_auth_domain_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, +#SoupAuthDomainBasicAuthCallback and +#SoupAuthDomainDigestAuthCallback), 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 +#SoupServer 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 #SoupMessage being authenticated + + + + the username from @msg + + + + the data passed to +soup_auth_domain_set_generic_auth_callback() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #SoupURI under which @auth is to be used + + + + the #SoupAuth to use + + + + + + + + + + + + Emitted when the manager requires the application to +provide authentication credentials. + +#SoupSession connects to this signal and emits its own +#SoupSession::authenticate signal when it is emitted, so +you shouldn't need to use this signal directly. + + + + + + the #SoupMessage being sent + + + + the #SoupAuth to authenticate + + + + %TRUE if this is the second (or later) attempt + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 #SoupSession, but libsoup will never attempt to +actually use this auth type. + + + + + + + + A data buffer, generally used to represent a chunk of a +#SoupMessageBody. + +@data is a #char because that's generally convenient; in some +situations you may need to cast it to #guchar or another type. + + + the data + + + + length of @data + + + + Creates a new #SoupBuffer containing @length bytes from @data. + + + the new #SoupBuffer. + + + + + how @data is to be used by the buffer + + + + data + + + + + + length of @data + + + + + + Creates a new #SoupBuffer containing @length bytes from @data. + +This function is exactly equivalent to soup_buffer_new() with +%SOUP_MEMORY_TAKE as first argument; it exists mainly for +convenience and simplifying language bindings. + + + the new #SoupBuffer. + + + + + data + + + + + + length of @data + + + + + + Creates a new #SoupBuffer containing @length bytes from @data. When +the #SoupBuffer is freed, it will call @owner_dnotify, passing +@owner to it. You must ensure that @data will remain valid until +@owner_dnotify is called. + +For example, you could use this to create a buffer containing data +returned from libxml without needing to do an extra copy: + +<informalexample><programlisting> +xmlDocDumpMemory (doc, &xmlbody, &len); +return soup_buffer_new_with_owner (xmlbody, len, xmlbody, + (GDestroyNotify)xmlFree); +</programlisting></informalexample> + +In this example, @data and @owner are the same, but in other cases +they would be different (eg, @owner would be a object, and @data +would be a pointer to one of the object's fields). + + + the new #SoupBuffer. + + + + + data + + + + + + length of @data + + + + pointer to an object that owns @data + + + + a function to free/unref @owner when +the buffer is freed + + + + + + Makes a copy of @buffer. In reality, #SoupBuffer is a refcounted +type, and calling soup_buffer_copy() will normally just increment +the refcount on @buffer and return it. However, if @buffer was +created with #SOUP_MEMORY_TEMPORARY memory, then soup_buffer_copy() +will actually return a copy of it, so that the data in the copy +will remain valid after the temporary buffer is freed. + + + the new (or newly-reffed) buffer + + + + + a #SoupBuffer + + + + + + Frees @buffer. (In reality, as described in the documentation for +soup_buffer_copy(), this is actually an "unref" operation, and may +or may not actually free @buffer.) + + + + + + + a #SoupBuffer + + + + + + Creates a #GBytes pointing to the same memory as @buffer. The +#GBytes will hold a reference on @buffer to ensure that it is not +freed while the #GBytes is still valid. + + + a new #GBytes which has the same content +as the #SoupBuffer. + + + + + a #SoupBuffer + + + + + + This function exists for use by language bindings, because it's not +currently possible to get the right effect by annotating the fields +of #SoupBuffer. + + + + + + + a #SoupBuffer + + + + the pointer +to the buffer data is stored here + + + + + + the length of the buffer data is stored here + + + + + + Gets the "owner" object for a buffer created with +soup_buffer_new_with_owner(). + + + the owner pointer + + + + + a #SoupBuffer created with soup_buffer_new_with_owner() + + + + + + Creates a new #SoupBuffer containing @length bytes "copied" from +@parent starting at @offset. (Normally this will not actually copy +any data, but will instead simply reference the same data as +@parent does.) + + + the new #SoupBuffer. + + + + + the parent #SoupBuffer + + + + offset within @parent to start at + + + + number of bytes to copy from @parent + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Macro to test the version of libsoup being compiled against. + + + + 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) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupCookieJar:accept-policy property. + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupCookieJarDB:filename property. (The +cookie-storage filename.) + + + + + + + + + + + + + + + + + + + Alias for the #SoupCookieJar:read-only property. (Whether +or not the cookie jar is read-only.) + + + + + + + + + + + + + + + + + + + Alias for the #SoupCookieJarText:filename property. (The +cookie-storage filename.) + + + + + + + + + + + + A constant corresponding to 1 day, for use with soup_cookie_new() +and soup_cookie_set_max_age(). + + + + + A constant corresponding to 1 hour, for use with soup_cookie_new() +and soup_cookie_set_max_age(). + + + + + A constant corresponding to 1 week, for use with soup_cookie_new() +and soup_cookie_set_max_age(). + + + + + A constant corresponding to 1 year, for use with soup_cookie_new() +and soup_cookie_set_max_age(). + + + + + + + + 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. + + + + + + + a #SoupCache + + + + + + Synchronously writes the cache index out to disk. Contrast with +soup_cache_flush(), which writes pending cache +<emphasis>entries</emphasis> to disk. + +You must call this before exiting if you want your cache data to +persist between sessions. + + + + + + + a #SoupCache + + + + + + This function will force all pending writes in the @cache to be +committed to disk. For doing so it will iterate the #GMainContext +associated with @cache's session as long as needed. + +Contrast with soup_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. + + + + + + + a #SoupCache + + + + + + Sets the maximum size of the cache. + + + + + + + a #SoupCache + + + + the maximum size of the cache, in bytes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The type of cache; this affects what kinds of responses will be +saved. + + a single-user cache + + + a shared cache + + + + + + + + + + + + + + The prototype for a chunk allocation callback. This should allocate +a new #SoupBuffer and return it for the I/O layer to read message +body data off the network into. + +If @max_len is non-0, it indicates the maximum number of bytes that +could be read, based on what is known about the message size. Note +that this might be a very large number, and you should not simply +try to allocate that many bytes blindly. If @max_len is 0, that +means that libsoup does not know how many bytes remain to be read, +and the allocator should return a buffer of a size that it finds +convenient. + +If the allocator returns %NULL, the message will be paused. It is +up to the application to make sure that it gets unpaused when it +becomes possible to allocate a new buffer. + Use #SoupRequest if you want to read into your +own buffers. + + + the new buffer (or %NULL) + + + + + the #SoupMessage the chunk is being allocated for + + + + the maximum length that will be read, or 0. + + + + the data passed to soup_message_set_chunk_allocator() + + + + + + A #SoupClientContext provides additional information about the +client making a particular request. In particular, you can use +soup_client_context_get_auth_domain() and +soup_client_context_get_auth_user() to determine if HTTP +authentication was used successfully. + +soup_client_context_get_remote_address() and/or +soup_client_context_get_host() can be used to get information for +logging or debugging purposes. soup_client_context_get_gsocket() may +also be of use in some situations (eg, tracking when multiple +requests are made on the same connection). + + + Retrieves the #SoupAddress associated with the remote end +of a connection. + Use soup_client_context_get_remote_address(), which returns +a #GSocketAddress. + + + the #SoupAddress +associated with the remote end of a connection, it may be +%NULL if you used soup_server_accept_iostream(). + + + + + a #SoupClientContext + + + + + + Checks whether the request associated with @client has been +authenticated, and if so returns the #SoupAuthDomain that +authenticated it. + + + a #SoupAuthDomain, or +%NULL if the request was not authenticated. + + + + + a #SoupClientContext + + + + + + Checks whether the request associated with @client has been +authenticated, and if so returns the username that the client +authenticated as. + + + the authenticated-as user, or %NULL if +the request was not authenticated. + + + + + a #SoupClientContext + + + + + + Retrieves the #GSocket that @client 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 @client is +associated with, %NULL if you used soup_server_accept_iostream(). + + + + + a #SoupClientContext + + + + + + 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 +soup_server_accept_iostream(). + + + + + a #SoupClientContext + + + + + + Retrieves the #GSocketAddress 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 soup_server_accept_iostream(). + + + + + a #SoupClientContext + + + + + + Retrieves the #GSocketAddress 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 soup_server_accept_iostream(). + + + + + a #SoupClientContext + + + + + + Retrieves the #SoupSocket that @client 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 (either by using weak references, or by +connecting to the #SoupSocket::disconnected signal), so that you do +not get fooled when the allocator reuses the memory address of a +previously-destroyed socket to represent a new socket. + use soup_client_context_get_gsocket(), which returns +a #GSocket. + + + the #SoupSocket that @client is +associated with. + + + + + a #SoupClientContext + + + + + + "Steals" the HTTP connection associated with @client from its +#SoupServer. This happens immediately, regardless of the current +state of the connection; if the response to the current +#SoupMessage has not yet finished being sent, then it will be +discarded; you can steal the connection from a +#SoupMessage:wrote-informational or #SoupMessage: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, @client will most +likely be freed as a side effect. + + + the #GIOStream formerly associated + with @client (or %NULL if @client was no longer associated with a + connection). No guarantees are made about what kind of #GIOStream + is returned. + + + + + a #SoupClientContext + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #SoupContentSniffer. + + + a new #SoupContentSniffer + + + + + Gets the number of bytes @sniffer needs in order to properly sniff +a buffer. + + + the number of bytes to sniff + + + + + a #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 + + + + + + + + + Gets the number of bytes @sniffer needs in order to properly sniff +a buffer. + + + the number of bytes to sniff + + + + + a #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 + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + the number of bytes to sniff + + + + + a #SoupContentSniffer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + An HTTP cookie. + +@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. + + + the cookie name + + + + the cookie value + + + + the "domain" attribute, or else the hostname that the +cookie came from. + + + + the "path" attribute, or %NULL + + + + the cookie expiration time, or %NULL for a session cookie + + + + %TRUE if the cookie should only be tranferred over SSL + + + + %TRUE if the cookie should not be exposed to scripts + + + + Creates a new #SoupCookie with the given attributes. (Use +soup_cookie_set_secure() and soup_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 +soup_cookie_set_expires().) + + + 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 #SoupURI + + + + + + Copies @cookie. + + + a copy of @cookie + + + + + a #SoupCookie + + + + + + Checks if the @cookie's domain and @host match in the sense that +@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 #SoupCookie + + + + + + 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 + + + + + + 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 soup_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 soup_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 + + + + + + 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 #SoupSession to a server). + + + the header + + + + + a #SoupCookie + + + + + + Serializes @cookie in the format used by the Set-Cookie header +(ie, for sending a cookie from a #SoupServer to a client). + + + the header + + + + + a #SoupCookie + + + + + + Parses @header and returns a #SoupCookie. (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 #SoupCookie, and you will need to fill in some +appropriate string for the domain if you want to actually make use +of the cookie. + + + 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, or %NULL + + + + + + + + + + Creates a new #SoupCookieJar. The base #SoupCookieJar 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 + + + + + + This function exists for backward compatibility, but does not do +anything any more; cookie jars are saved automatically when they +are changed. + This is a no-op. + + + + + + + a #SoupCookieJar + + + + + + Adds @cookie to @jar, emitting the '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, emitting the '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, emitting the '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 +soup_cookie_jar_add_cookie_full(). + + + + + + + a #SoupCookieJar + + + + the URI for the main document + + + + a #SoupCookie + + + + + + Constructs a #GSList 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. + + + a #GSList +with all the cookies in the @jar. + + + + + + + a #SoupCookieJar + + + + + + Deletes @cookie from @jar, emitting the 'changed' signal. + + + + + + + a #SoupCookieJar + + + + a #SoupCookie + + + + + + Gets @jar's #SoupCookieJarAcceptPolicy + + + the #SoupCookieJarAcceptPolicy set in the @jar + + + + + a #SoupCookieJar + + + + + + Retrieves the list of cookies that would be sent with a request to @uri +as a #GSList of #SoupCookie 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 #SoupCookieJar 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 #SoupURI + + + + whether or not the return value is being passed directly +to an HTTP operation + + + + + + 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 #SoupCookieJar 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 #SoupURI + + + + 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 + + + + + + This function exists for backward compatibility, but does not do +anything any more; cookie jars are saved automatically when they +are changed. + This is a no-op. + + + + + + + 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 #SoupCookieJarAcceptPolicy +%SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY is set you'll need to use +soup_cookie_jar_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 + + + + + + + + + + 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 soup_message_set_first_party() +on each outgoing #SoupMessage, setting the #SoupURI 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. + + + + + + + + + + + + + + + + a #SoupCookieJar + + + + + + + + + + %TRUE if @jar storage is persistent or %FALSE otherwise. + + + + + a #SoupCookieJar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a #SoupCookieJarDB. + +@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 '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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a #SoupCookieJarText. + +@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 '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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A date and time. The date is assumed to be in the (proleptic) +Gregorian calendar. The time is in UTC if @utc is %TRUE. Otherwise, +the time is a local time, and @offset gives the offset from UTC in +minutes (such that adding @offset to the time would give the +correct UTC time). If @utc is %FALSE and @offset is 0, then the +%SoupDate represents a "floating" time with no associated timezone +information. + + + the year, 1 to 9999 + + + + the month, 1 to 12 + + + + day of the month, 1 to 31 + + + + hour of the day, 0 to 23 + + + + minute, 0 to 59 + + + + second, 0 to 59 (or up to 61 in the case of leap seconds) + + + + %TRUE if the date is in UTC + + + + offset from UTC + + + + Creates a #SoupDate representing the indicated time, UTC. + + + a new #SoupDate + + + + + the year (1-9999) + + + + the month (1-12) + + + + the day of the month (1-31, as appropriate for @month) + + + + the hour (0-23) + + + + the minute (0-59) + + + + the second (0-59, or up to 61 for leap seconds) + + + + + + Creates a #SoupDate representing a time @offset_seconds after the +current time (or before it, if @offset_seconds is negative). If +offset_seconds is 0, returns the current time. + +If @offset_seconds would indicate a time not expressible as a +<type>time_t</type>, the return value will be clamped into range. + + + a new #SoupDate + + + + + offset from current time + + + + + + Parses @date_string and tries to extract a date from it. This +recognizes all of the "HTTP-date" formats from RFC 2616, all ISO +8601 formats containing both a time and a date, RFC 2822 dates, +and reasonable approximations thereof. (Eg, it is lenient about +whitespace, leading "0"s, etc.) + + + a new #SoupDate, or %NULL if @date_string +could not be parsed. + + + + + the date in some plausible format + + + + + + Creates a #SoupDate corresponding to @when + + + a new #SoupDate + + + + + a <type>time_t</type> + + + + + + Copies @date. + + + + + + + a #SoupDate + + + + + + Frees @date. + + + + + + + a #SoupDate + + + + + + Gets @date's day. + + + @date's day + + + + + a #SoupDate + + + + + + Gets @date's hour. + + + @date's hour + + + + + a #SoupDate + + + + + + Gets @date's minute. + + + @date's minute + + + + + a #SoupDate + + + + + + Gets @date's month. + + + @date's month + + + + + a #SoupDate + + + + + + Gets @date's offset from UTC. + + + @date's offset from UTC. If soup_date_get_utc() +returns %FALSE but soup_date_get_offset() returns 0, that means the +date is a "floating" time with no associated offset information. + + + + + a #SoupDate + + + + + + Gets @date's second. + + + @date's second + + + + + a #SoupDate + + + + + + Gets @date's UTC flag + + + %TRUE if @date is UTC. + + + + + a #SoupDate + + + + + + Gets @date's year. + + + @date's year + + + + + a #SoupDate + + + + + + Determines if @date is in the past. + + + %TRUE if @date is in the past + + + + + a #SoupDate + + + + + + Converts @date to a string in the format described by @format. + + + @date as a string + + + + + a #SoupDate + + + + the format to generate the date in + + + + + + Converts @date to a <type>time_t</type>, assumming it to be in +UTC. + +If @date is not representable as a <type>time_t</type>, it will be +clamped into range. (In particular, some HTTP cookies have +expiration dates after "Y2.038k" (2038-01-19T03:14:07Z).) + + + @date as a <type>time_t</type> + + + + + a #SoupDate + + + + + + Converts @date to a #GTimeVal. + + + + + + + a #SoupDate + + + + a #GTimeVal structure in which to store the converted time. + + + + + + + Date formats that soup_date_to_string() can use. + +@SOUP_DATE_HTTP and @SOUP_DATE_COOKIE always coerce the time to +UTC. @SOUP_DATE_ISO8601_XMLRPC uses the time as given, ignoring the +offset completely. @SOUP_DATE_RFC2822 and the other ISO 8601 +variants use the local time, appending the offset information if +available. + +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". + + + RFC 2822 format, eg "Sun, 6 Nov 1994 09:49:37 -0100" + + + ISO 8601 date/time with no optional +punctuation. Eg, "19941106T094937-0100". + + + ISO 8601 date/time with all optional +punctuation. Eg, "1994-11-06T09:49:37-01:00". + + + An alias for @SOUP_DATE_ISO8601_FULL. + + + ISO 8601 date/time as used by XML-RPC. +Eg, "19941106T09:49:37". + + + + 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 +<literal>"multipart/form-data"</literal>; the MIME type used for +posting form data that contains files to be uploaded. + + + + + A macro containing the value +<literal>"application/x-www-form-urlencoded"</literal>; the default +MIME type for POSTing HTML form data. + + + + + + + + Creates a new #SoupHSTSEnforcer. The base #SoupHSTSEnforcer class +does not support persistent storage of HSTS policies, see +#SoupHSTSEnforcerDB for that. + + + a new #SoupHSTSEnforcer + + + + + + + + + + + + + + + + + + + + + + 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 g_list_free_full() and g_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 g_list_free_full() and +soup_hsts_policy_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 soup_hsts_policy_new_session_policy(), the policy +will not expire and will be enforced during the lifetime of +@hsts_enforcer's #SoupSession. + + + + + + + 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 #SoupSession +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 + + + + + + Emitted when @hsts_enforcer has upgraded the protocol +for @message to HTTPS as a result of matching its domain with +a HSTS policy. + + + + + + the message for which HSTS is being enforced + + + + + + + + + The parent class. + + + + + + + %TRUE if @hsts_enforcer storage is persistent or %FALSE otherwise. + + + + + a #SoupHSTSEnforcer + + + + + + + + + + %TRUE if access to @domain should happen over HTTPS, false +otherwise. + + + + + a #SoupHSTSEnforcer + + + + a domain. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a #SoupHSTSEnforcerDB. + +@filename will be read in during the initialization of a +#SoupHSTSEnforcerDB, 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 +#SoupHSTSEnforcerDB will be written to @filename when +#SoupHSTSEnforcer::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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + An HTTP Strict Transport Security policy. + +@domain represents the host that this policy applies to. The domain +must be IDNA-canonicalized. soup_hsts_policy_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. + + + The domain or hostname that the policy applies to + + + + The maximum age, in seconds, that the policy is valid + + + + the policy expiration time, or %NULL for a permanent session policy + + + + %TRUE if the policy applies on subdomains + + + + Creates a new #SoupHSTSPolicy 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 #SoupHSTSPolicy. + + + a new #SoupHSTSPolicy, or %NULL if no valid +"Strict-Transport-Security" response header was found. + + + + + a #SoupMessage + + + + + + Full version of #soup_hsts_policy_new(), to use with an existing +expiration date. See #soup_hsts_policy_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 #SoupHSTSPolicy with the given attributes. +A session policy is a policy that is valid during the lifetime of +the #SoupHSTSEnforcer 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 + + + + + + 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 soup_hsts_policy_new_session_policy() for details. + + + %TRUE if @policy is permanent, %FALSE otherwise + + + + + a #SoupHSTSPolicy + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Indicates the HTTP protocol version being used. + + HTTP 1.0 (RFC 1945) + + + HTTP 1.1 (RFC 2616) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupLogger:level property, qv. + + + + + Alias for the #SoupLogger:max-body-size property, qv. + + + + + + + + Creates a new #SoupLogger with the given debug level. If @level is +%SOUP_LOGGER_LOG_BODY, @max_body_size gives the maximum number of +bytes of the body that will be logged. (-1 means "no limit".) + +If you need finer control over what message parts are and aren't +logged, use soup_logger_set_request_filter() and +soup_logger_set_response_filter(). + + + a new #SoupLogger + + + + + the debug level + + + + the maximum body size to output, or -1 + + + + + + Sets @logger to watch @session and print debug information for +its messages. + +(The session will take a reference on @logger, which will be +removed when you call soup_logger_detach(), or when the session is +destroyed.) + Use soup_session_add_feature() instead. + + + + + + + a #SoupLogger + + + + a #SoupSession + + + + + + Stops @logger from watching @session. + Use soup_session_remove_feature() instead. + + + + + + + a #SoupLogger + + + + a #SoupSession + + + + + + Sets up an alternate log printing routine, if you don't want +the log to go to <literal>stdout</literal>. + + + + + + + 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 soup_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 soup_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 #SoupLogger: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 #SoupLoggerLogLevel value indicating how much of the +message to log. Eg, it might choose between %SOUP_LOGGER_LOG_BODY +and %SOUP_LOGGER_LOG_HEADERS depending on the Content-Type. + + + a #SoupLoggerLogLevel value indicating how much of +the message to log + + + + + the #SoupLogger + + + + the message being logged + + + + the data passed to soup_logger_set_request_filter() +or soup_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: + +<informalexample><programlisting> +printf ("%c %s\n", direction, data); +</programlisting></informalexample> + + + + + + + the #SoupLogger + + + + the level of the information being printed. + + + + a single-character prefix to @data + + + + data to print + + + + the data passed to soup_logger_set_printer() + + + + + + Like soup_get_major_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + + + + + + + + + + + + + + + Alias for the #SoupMessage:first-party property. (The +#SoupURI loaded in the application when the message was +queued.) + + + + + Alias for the #SoupMessage:flags property. (The message's +#SoupMessageFlags.) + + + + + + + + + + + + Alias for the #SoupMessage:http-version property. (The +message's #SoupHTTPVersion.) + + + + + Alias for the #SoupMessage:method property. (The message's +HTTP method.) + + + + + Sets the priority of the #SoupMessage. See +soup_message_set_priority() for further details. + + + + + Alias for the #SoupMessage:reason-phrase property. (The +message's HTTP response reason phrase.) + + + + + Alias for the #SoupMessage:request-body property. (The +message's HTTP request body.) + + + + + Alias for the #SoupMessage:request-body-data property. (The +message's HTTP request body, as a #GBytes.) + + + + + Alias for the #SoupMessage:request-headers property. (The +message's HTTP request headers.) + + + + + Alias for the #SoupMessage:response-body property. (The +message's HTTP response body.) + + + + + Alias for the #SoupMessage:response-body-data property. (The +message's HTTP response body, as a #GBytes.) + + + + + Alias for the #SoupMessage:response-headers property. (The +message's HTTP response headers.) + + + + + Alias for the #SoupMessage:server-side property. (%TRUE if +the message was created by #SoupServer.) + + + + + Alias for the #SoupMessage:status-code property. (The +message's HTTP response status code.) + + + + + Alias for the #SoupMessage:tls-certificate property. (The +TLS certificate associated with the message, if any.) + + + + + Alias for the #SoupMessage:tls-errors property. (The +verification errors on #SoupMessage:tls-certificate.) + + + + + Alias for the #SoupMessage:uri property. (The message's +#SoupURI.) + + + + + Like soup_get_micro_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + Like soup_get_minor_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + + + + + + + + + + + + + + + + + + + + + + Describes how #SoupBuffer should use the data passed in by the +caller. + +See also soup_buffer_new_with_owner(), which allows to you create a +buffer containing data which is owned by another object. + + 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 for the +#SoupBuffer's use; libsoup will assume ownership of it and free it +(with g_free()) when it is done with it. + + + The passed-in data belongs to the caller; the +#SoupBuffer will copy it into new memory, leaving the caller free +to reuse the original memory. + + + The passed-in data belongs to the caller, +but will remain valid for the lifetime of the #SoupBuffer. The +difference between this and @SOUP_MEMORY_STATIC is that if you copy +a @SOUP_MEMORY_TEMPORARY buffer, it will make a copy of the memory +as well, rather than reusing the original memory. + + + + Represents an HTTP message being sent or received. + +@status_code will normally be a #SoupStatus value, eg, +%SOUP_STATUS_OK, though of course it might actually be an unknown +status code. @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 @reason_phrase in user-visible +messages. Rather, you should look at @status_code, and determine an +end-user-appropriate message based on that and on what you were +trying to do. + +As described in the #SoupMessageBody documentation, the +@request_body and @response_body <literal>data</literal> fields +will not necessarily be filled in at all times. When the body +fields are filled in, they will be terminated with a '\0' byte +(which is not included in the <literal>length</literal>), so you +can use them as ordinary C strings (assuming that you know that the +body doesn't have any other '\0' bytes). + +For a client-side #SoupMessage, @request_body's +<literal>data</literal> is usually filled in right before libsoup +writes the request to the network, but you should not count on +this; use soup_message_body_flatten() if you want to ensure that +<literal>data</literal> is filled in. If you are not using +#SoupRequest to read the response, then @response_body's +<literal>data</literal> will be filled in before +#SoupMessage::finished is emitted. (If you are using #SoupRequest, +then the message body is not accumulated by default, so +@response_body's <literal>data</literal> will always be %NULL.) + +For a server-side #SoupMessage, @request_body's %data will be +filled in before #SoupMessage::got_body is emitted. + +To prevent the %data field from being filled in at all (eg, if you +are handling the data from a #SoupMessage::got_chunk, and so don't +need to see it all at the end), call +soup_message_body_set_accumulate() on @response_body or +@request_body as appropriate, passing %FALSE. + + + Creates a new empty #SoupMessage, 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 empty #SoupMessage, which will connect to @uri + + + the new #SoupMessage + + + + + the HTTP method for the created request + + + + the destination endpoint (as a #SoupURI) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Adds a signal handler to @msg for @signal, as with +g_signal_connect(), but the @callback will only be run if @msg's +incoming messages headers (that is, the +<literal>request_headers</literal> for a client #SoupMessage, or +the <literal>response_headers</literal> for a server #SoupMessage) +contain a header named @header. + + + the handler ID from g_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, as with +g_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. For a client #SoupMessage, this means it can't be a "wrote" +signal. For a server #SoupMessage, this means it can't be a "got" +signal. + + + the handler ID from g_signal_connect() + + + + + a #SoupMessage + + + + signal to connect the handler to. + + + + status code to match against + + + + the header handler + + + + data to pass to @handler_cb + + + + + + + + + + + + + + + + + + + + + + + + + + This disables the actions of #SoupSessionFeature<!-- -->s with the +given @feature_type (or a subclass of that type) on @msg, so that +@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 #SoupSessionFeature + + + + + + + + + + + + + + + + + Gets the address @msg's URI points to. After first setting the +URI on a message, this will be unresolved, although the message's +session will resolve it before sending the message. + + + the address @msg's URI points to + + + + + a #SoupMessage + + + + + + Gets @msg's first-party #SoupURI + + + the @msg's first party #SoupURI + + + + + a #SoupMessage + + + + + + Gets the flags on @msg + + + the flags + + + + + a #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 + + + + + + If @msg is using https (or attempted to use https but got +%SOUP_STATUS_SSL_FAILED), this retrieves the #GTlsCertificate +associated with its connection, and the #GTlsCertificateFlags +showing what problems, if any, have been found with that +certificate. + +<note><para>This is only meaningful with messages processed by a #SoupSession and is +not useful for messages received by a #SoupServer</para></note> + + + %TRUE if @msg used/attempted https, %FALSE if not + + + + + a #SoupMessage + + + + @msg's TLS certificate + + + + the verification status of @certificate + + + + + + Retrieves the #SoupMessagePriority. If not set this value defaults +to #SOUP_MESSAGE_PRIORITY_NORMAL. + + + the priority of the message. + + + + + a #SoupMessage + + + + + + If @msg is associated with a #SoupRequest, this returns that +request. Otherwise it returns %NULL. + + + @msg's associated #SoupRequest + + + + + a #SoupMessage + + + + + + Gets @msg's URI + + + the URI @msg is targeted for. + + + + + a #SoupMessage + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Determines whether or not @msg's connection can be kept alive for +further requests after processing @msg, based on the HTTP version, +Connection header, etc. + + + %TRUE or %FALSE. + + + + + a #SoupMessage + + + + + + + + + + + + + + + + + Sets an alternate chunk-allocation function to use when reading +@msg's body when using the traditional (ie, +non-#SoupRequest<!-- -->-based) API. Every time data is available +to read, libsoup will call @allocator, which should return a +#SoupBuffer. (See #SoupChunkAllocator for additional details.) +Libsoup will then read data from the network into that buffer, and +update the buffer's <literal>length</literal> to indicate how much +data it read. + +Generally, a custom chunk allocator would be used in conjunction +with soup_message_body_set_accumulate() %FALSE and +#SoupMessage::got_chunk, as part of a strategy to avoid unnecessary +copying of data. However, you cannot assume that every call to the +allocator will be followed by a call to your +#SoupMessage::got_chunk handler; if an I/O error occurs, then the +buffer will be unreffed without ever having been used. If your +buffer-allocation strategy requires special cleanup, use +soup_buffer_new_with_owner() rather than doing the cleanup from the +#SoupMessage::got_chunk handler. + +The other thing to remember when using non-accumulating message +bodies is that the buffer passed to the #SoupMessage::got_chunk +handler will be unreffed after the handler returns, just as it +would be in the non-custom-allocated case. If you want to hand the +chunk data off to some other part of your program to use later, +you'll need to ref the #SoupBuffer (or its owner, in the +soup_buffer_new_with_owner() case) to ensure that the data remains +valid. + #SoupRequest provides a much simpler API that lets you +read the response directly into your own buffers without needing to +mess with callbacks, pausing/unpausing, etc. + + + + + + + a #SoupMessage + + + + the chunk allocator callback + + + + data to pass to @allocator + + + + destroy notifier to free @user_data when @msg is +destroyed + + + + + + Sets @first_party as the main document #SoupURI for @msg. For +details of when and how this is used refer to the documentation for +#SoupCookieJarAcceptPolicy. + + + + + + + a #SoupMessage + + + + the #SoupURI for the @msg's first party + + + + + + Sets the specified flags on @msg. + + + + + + + a #SoupMessage + + + + a set of #SoupMessageFlags values + + + + + + Sets the HTTP version on @msg. The default version is +%SOUP_HTTP_1_1. Setting it to %SOUP_HTTP_1_0 will prevent certain +functionality from being used. + + + + + + + a #SoupMessage + + + + the HTTP version + + + + + + 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 #SoupSessionSync +(or with synchronous messages on a plain #SoupSession) because in +the synchronous/blocking case, priority ends up being determined +semi-randomly by thread scheduling. + + + + + + + a #SoupMessage + + + + the #SoupMessagePriority + + + + + + Sets @msg's status_code to @status_code and adds a Location header +pointing to @redirect_uri. Use this from a #SoupServer 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 +<emphasis>and query</emphasis> of @msg's URI. + + + + + + + a #SoupMessage + + + + a 3xx status code + + + + the URI to redirect @msg to + + + + + + Convenience function to set the request body of a #SoupMessage. If +@content_type is %NULL, the request body must be empty as well. + + + + + + + the message + + + + MIME Content-Type of the body + + + + a #SoupMemoryUse describing how to handle @req_body + + + + + a data buffer containing the body of the message request. + + + + + + the byte length of @req_body. + + + + + + Convenience function to set the response body of a #SoupMessage. 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, it will also set @msg's reason_phrase. + + + + + + + a #SoupMessage + + + + an HTTP status code + + + + + + Sets @msg's status code and reason phrase. + + + + + + + a #SoupMessage + + + + an HTTP status code + + + + a description of the status + + + + + + 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 call +soup_session_requeue_message(). + + + + + + + a #SoupMessage + + + + the new #SoupURI + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #SoupURI loaded in the application when the message was +queued. + + + + + + + + + + + + + + + + + + + + + + The message's HTTP request body, as a #GBytes. + + + + + + + + + + The message's HTTP response body, as a #GBytes. + + + + + + + + + + + + + The #GTlsCertificate associated with the message + + + + The verification errors on #SoupMessage:tls-certificate + + + + + + + + + + the HTTP method + + + + the HTTP status code + + + + the status phrase associated with @status_code + + + + the request body + + + + the request headers + + + + the response body + + + + the response headers + + + + This signal is emitted after #SoupMessage::got-headers, and +before the first #SoupMessage::got-chunk. 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 #SoupMessage::got-headers, and @type is +%NULL. + +If the #SoupContentSniffer feature is enabled, and the +sniffer decided to perform sniffing, the first +#SoupMessage::got-chunk emission may be delayed, so that the +sniffer has enough data to correctly sniff the content. It +notified the library user that the content has been +sniffed, and allows it to change the header contents in the +message, if desired. + +After this signal is emitted, the data that was spooled so +that sniffing could be done is delivered on the first +emission of #SoupMessage::got-chunk. + + + + + + the content type that we got from sniffing + + + + a #GHashTable with the parameters + + + + + + + + + Emitted when all HTTP processing is finished for a message. +(After #SoupMessage::got_body for client-side messages, or +after #SoupMessage::wrote_body for server-side messages.) + + + + + + Emitted after receiving the complete message body. (For a +server-side message, this means it has received the request +body. For a client-side message, this means it has received +the response body and is nearly done with the message.) + +See also soup_message_add_header_handler() and +soup_message_add_status_code_handler(), which can be used +to connect to a subset of emissions of this signal. + + + + + + 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. + +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. + + + + + + the just-read chunk + + + + + + Emitted after receiving all message headers for a message. +(For a client-side message, this is after receiving the +Status-Line and response headers; for a server-side +message, it is after receiving the Request-Line and request +headers.) + +See also soup_message_add_header_handler() and +soup_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 #SoupMessage::got_body handler rather +than a #SoupMessage::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 to indicate that some network-related event +related to @msg has occurred. This essentially proxies the +#GSocketClient::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 #GSocketClient::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 when a request that was already sent once is now +being sent again (eg, 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. (For a client-side message, this means that +libsoup is done writing and is now waiting for the response +from the server. For a server-side message, this means that +libsoup has finished writing the response and is nearly +done with the message.) + + + + + + Emitted immediately after writing a portion of the message +body to the network. + +Unlike #SoupMessage::wrote_chunk, this is emitted after +every successful write() call, not only after finishing a +complete "chunk". + + + + + + the data written + + + + + + Emitted immediately after writing a body chunk for a message. + +Note that this signal is not parallel to +#SoupMessage::got_chunk; it is emitted only when a complete +chunk (added with soup_message_body_append() or +soup_message_body_append_buffer()) has been written. To get +more useful continuous progress information, use +#SoupMessage::wrote_body_data. + + + + + + Emitted immediately after writing the headers for a +message. (For a client-side message, this is after writing +the request headers; for a server-side message, it is after +writing the response headers.) + + + + + + Emitted immediately after writing a 1xx (Informational) +response for a (server-side) message. + + + + + + + A #SoupMessage request or response body. + +Note that while @length always reflects the full length of the +message body, @data is normally %NULL, and will only be filled in +after soup_message_body_flatten() is called. For client-side +messages, this automatically happens for the response body after it +has been fully read, unless you set the +%SOUP_MESSAGE_OVERWRITE_CHUNKS flags. 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 #SoupMessageBody. #SoupMessage 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. (#SoupMessageBody uses +#SoupBuffers internally, so this is normally a constant-time +operation that doesn't actually require copying the data in +@buffer.) + + + + + + + a #SoupMessageBody + + + + a #SoupBuffer + + + + + + Appends @length bytes from @data to @body. + +This function is exactly equivalent to soup_message_body_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 (plus an additional '\0' byte not counted by @body's +length field). + + + a #SoupBuffer containing the same data as @body. +(You must free this buffer if you do not want it.) + + + + + a #SoupMessageBody + + + + + + Frees @body. You will not normally need to use this, as +#SoupMessage frees its associated message bodies automatically. + + + + + + + a #SoupMessageBody + + + + + + Gets the accumulate flag on @body; see +soup_message_body_set_accumulate() for details. + + + the accumulate flag for @body. + + + + + a #SoupMessageBody + + + + + + Gets a #SoupBuffer 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 +soup_message_body_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 +soup_message_body_complete() has been called or not; if it has, +then soup_message_body_get_chunk() will return a 0-length chunk +(indicating the end of @body). If it has not, then +soup_message_body_get_chunk() will return %NULL (indicating that +@body may still potentially have more data, but that data is not +currently available). + + + a #SoupBuffer, or %NULL. + + + + + a #SoupMessageBody + + + + an offset + + + + + + Handles the #SoupMessageBody part of receiving a chunk of data from +the network. Normally this means appending @chunk to @body, exactly +as with soup_message_body_append_buffer(), 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 #SoupBuffer received from the network + + + + + + 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. + +In particular, if you set this flag to %FALSE on an "incoming" +message body (that is, the #SoupMessage:response_body of a +client-side message, or #SoupMessage:request_body of a server-side +message), this will cause each chunk of the body to be discarded +after its corresponding #SoupMessage::got_chunk signal is emitted. +(This is equivalent to setting the deprecated +%SOUP_MESSAGE_OVERWRITE_CHUNKS flag on the message.) + +If you set this flag to %FALSE on the #SoupMessage:response_body of +a server-side message, it will cause each chunk of the body to be +discarded after its corresponding #SoupMessage::wrote_chunk signal +is emitted. + +If you set the flag to %FALSE on the #SoupMessage: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 +#SoupMessage: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. However, if you set the +%SOUP_MESSAGE_CAN_REBUILD flag on the message, then the chunks will +be discarded, and you will be responsible for recreating the +request body after the #SoupMessage::restarted signal is emitted. + + + + + + + a #SoupMessageBody + + + + whether or not to accumulate body chunks in @body + + + + + + Deletes all of the data in @body. + + + + + + + a #SoupMessageBody + + + + + + Handles the #SoupMessageBody 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 #SoupBuffer returned from soup_message_body_get_chunk() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Various flags that can be set on a #SoupMessage to alter its +behavior. + + The session should not follow redirect + (3xx) responses received by this message. + + + The caller will rebuild the request + body if the message is restarted; see + soup_message_body_set_accumulate() for more details. + + + Deprecated: equivalent to calling + soup_message_body_set_accumulate() on the incoming message body + (ie, #SoupMessage:response_body for a client-side request), + passing %FALSE. + + + Set by #SoupContentDecoder to + indicate that it has removed the Content-Encoding on a message (and + so headers such as Content-Length may no longer accurately describe + the body). + + + if set after an https response + has been received, indicates that the server's SSL certificate is + trusted according to the session's CA. + + + Requests that the message should be + sent on a newly-created connection, not reusing an existing + persistent connection. Note that messages with non-idempotent + #SoupMessage:method<!-- -->s behave this way by default, unless + #SOUP_MESSAGE_IDEMPOTENT is set. + + + The message is considered idempotent, + regardless its #SoupMessage:method, and allows reuse of existing + idle connections, instead of always requiring a new one, unless + #SOUP_MESSAGE_NEW_CONNECTION is set. + + + Request that a new connection is + created for the message if there aren't idle connections available + and it's not possible to create new connections due to any of the + connection limits has been reached. If a dedicated connection is + eventually created for this message, it will be dropped when the + message finishes. Since 2.50 + + + The #SoupAuthManager 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 #SoupSession::authenticate signal will + be emitted, if you want to disable authentication for a message use + soup_message_disable_feature() passing #SOUP_TYPE_AUTH_MANAGER instead. Since 2.58 + + + + The HTTP message headers associated with a request or response. + + + Creates a #SoupMessageHeaders. (#SoupMessage 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 +soup_message_headers_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 soup_message_headers_get(), 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 +soup_message_headers_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 @hdrs. + + + + + + + a #SoupMessageHeaders + + + + + + Frees the array of ranges returned from soup_message_headers_get_ranges(). + + + + + + + a #SoupMessageHeaders + + + + an array of #SoupRange + + + + + + Gets the value of header @name in @hdrs. + +This method was supposed to work correctly for both single-valued +and list-valued headers, but because some HTTP clients/servers +mistakenly send multiple copies of headers that are supposed to be +single-valued, it sometimes returns incorrect results. To fix this, +the methods soup_message_headers_get_one() and +soup_message_headers_get_list() were introduced, so callers can +explicitly state which behavior they are expecting. + Use soup_message_headers_get_one() or +soup_message_headers_get_list() instead. + + + as with soup_message_headers_get_list(). + + + + + a #SoupMessageHeaders + + + + header name + + + + + + 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 #SoupMultipart 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 soup_message_headers_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 soup_message_headers_get_one(). + +If @name appears multiple times in @hdrs, +soup_message_headers_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 <emphasis>not</emphasis> comma-delimited lists, and +which therefore can only appear at most once in the headers. For +list-valued headers, use soup_message_headers_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 +soup_message_headers_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 #SoupRange, 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. + +<note><para> +#SoupServer 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. +</para></note> + + + %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 +soup_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 + + + + + + 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 soup_message_headers_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 soup_message_headers_get_content_disposition() for a discussion +of how Content-Disposition is used in HTTP. + + + + + + + a #SoupMessageHeaders + + + + the disposition-type + + + + additional +parameters, or %NULL + + + + + + + + + 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 +soup_message_headers_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.) + +<note><para> +#SoupServer has built-in handling for range requests, and you do +not normally need to call this function youself. See +soup_message_headers_get_ranges() for more details. +</para></note> + + + + + + + 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, +optionally with additional parameters specified in @params. + + + + + + + a #SoupMessageHeaders + + + + the MIME type + + + + additional +parameters, or %NULL + + + + + + + + + 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 #SoupRange. + +If you need to request multiple ranges, use +soup_message_headers_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 +soup_message_headers_set_range().) + + + + + + + a #SoupMessageHeaders + + + + an array of #SoupRange + + + + the length of @range + + + + + + + The callback passed to soup_message_headers_foreach(). + + + + + + + the header name + + + + the header value + + + + the data passed to soup_message_headers_foreach() + + + + + + An opaque type used to iterate over a %SoupMessageHeaders +structure. + +After intializing the iterator with +soup_message_headers_iter_init(), call +soup_message_headers_iter_next() to fetch data from it. + +You may not modify the headers while iterating over them. + + + + + + + + Yields the next name/value pair in the %SoupMessageHeaders being +iterated by @iter. If @iter has already yielded the last header, +then soup_message_headers_iter_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 + + + + + + Initializes @iter for iterating @hdrs. + + + + + + + a pointer to a %SoupMessageHeadersIter +structure + + + + a %SoupMessageHeaders + + + + + + + Value passed to soup_message_headers_new() to set certain default +behaviors. + + request headers + + + response headers + + + multipart body part headers + + + + Priorities that can be set on a #SoupMessage 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 + #SoupMessage with the default priority will be processed first. + + + The default priotity, this is the + priority assigned to the #SoupMessage by default. + + + High priority, a #SoupMessage with + this priority will be processed before the ones with the default + priority. + + + The highest priority, use this + for very urgent #SoupMessage 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 +<literal>multipart/byte-ranges</literal> and +<literal>multipart/form-data</literal>. + +Although the headers of a #SoupMultipart 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 +#SoupMultipart for handling real MIME multiparts. + + + Creates a new empty #SoupMultipart with a randomly-generated +boundary string. Note that @mime_type must be the full MIME type, +including "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 #SoupMultipart + + + 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, using +"Content-Disposition: form-data", as per the HTML forms +specification. See soup_form_request_new_from_multipart() for more +details. + + + + + + + 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, using +"Content-Disposition: form-data", as per the HTML forms +specification. See soup_form_request_new_from_multipart() for more +details. + + + + + + + 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 + + + + + + + + + + Creates a new #SoupMultipartInputStream that wraps the +#GInputStream obtained by sending the #SoupRequest. Reads should +not be done directly through this object, use the input streams +returned by soup_multipart_input_stream_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 #SoupMessageHeaders that are returned are owned by the +#SoupMultipartInputStream and will be replaced when a call is made +to soup_multipart_input_stream_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 #SoupMessageHeaders +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 +#SoupMultipartInputStream and this function or its async +counterpart need to be called to obtain the first part for +reading. + +After calling this function, +soup_multipart_input_stream_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. + + + a new #GInputStream, or +%NULL if there are no more parts + + + + + the #SoupMultipartInputStream + + + + a #GCancellable + + + + + + Obtains a #GInputStream for the next request. See +soup_multipart_input_stream_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 +#GInputStream for reading the next part or %NULL if there are no +more parts. + + + + + a #SoupMultipartInputStream. + + + + a #GAsyncResult. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use SoupProxyURIResolver.get_proxy_uri_async instead + + + + + + + + + + + + + + + + + + + + + + + + + + + Use SoupProxyURIResolver.get_proxy_uri_sync() instead + + + + + + + + + + + + + + + + + + + + + Use SoupProxyURIResolver.get_proxy_uri_async instead + + + + + + + + + + + + + + + + + + + + + + + + + + + Use SoupProxyURIResolver.get_proxy_uri_sync() instead + + + + + + + + + + + + + + + + + + + + + + Use SoupProxyURIResolver instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Asynchronously determines a proxy URI to use for @msg and calls +@callback. + #SoupProxyURIResolver is deprecated in favor of +#GProxyResolver + + + + + + + the #SoupProxyURIResolver + + + + the #SoupURI you want a proxy for + + + + the #GMainContext to invoke @callback in + + + + a #GCancellable, or %NULL + + + + callback to invoke with the proxy address + + + + data for @callback + + + + + + Synchronously determines a proxy URI to use for @uri. If @uri +should be sent via proxy, *@proxy_uri will be set to the URI of the +proxy, else it will be set to %NULL. + #SoupProxyURIResolver is deprecated in favor of +#GProxyResolver + + + %SOUP_STATUS_OK if successful, or a transport-level +error. + + + + + the #SoupProxyURIResolver + + + + the #SoupURI you want a proxy for + + + + a #GCancellable, or %NULL + + + + on return, will contain the proxy URI + + + + + + Asynchronously determines a proxy URI to use for @msg and calls +@callback. + #SoupProxyURIResolver is deprecated in favor of +#GProxyResolver + + + + + + + the #SoupProxyURIResolver + + + + the #SoupURI you want a proxy for + + + + the #GMainContext to invoke @callback in + + + + a #GCancellable, or %NULL + + + + callback to invoke with the proxy address + + + + data for @callback + + + + + + Synchronously determines a proxy URI to use for @uri. If @uri +should be sent via proxy, *@proxy_uri will be set to the URI of the +proxy, else it will be set to %NULL. + #SoupProxyURIResolver is deprecated in favor of +#GProxyResolver + + + %SOUP_STATUS_OK if successful, or a transport-level +error. + + + + + the #SoupProxyURIResolver + + + + the #SoupURI you want a proxy for + + + + a #GCancellable, or %NULL + + + + on return, will contain the proxy URI + + + + + + + Callback for soup_proxy_uri_resolver_get_proxy_uri_async() + + + + + + + the #SoupProxyURIResolver + + + + a #SoupStatus + + + + the resolved proxy URI, or %NULL + + + + data passed to soup_proxy_uri_resolver_get_proxy_uri_async() + + + + + + + + + + + + + + + + + + the #SoupProxyURIResolver + + + + the #SoupURI you want a proxy for + + + + the #GMainContext to invoke @callback in + + + + a #GCancellable, or %NULL + + + + callback to invoke with the proxy address + + + + data for @callback + + + + + + + + + + %SOUP_STATUS_OK if successful, or a transport-level +error. + + + + + the #SoupProxyURIResolver + + + + the #SoupURI you want a proxy for + + + + a #GCancellable, or %NULL + + + + on return, will contain the proxy URI + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupRequest:session property, qv. + + + + + Alias for the #SoupRequest:uri property, qv. + + + + + 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 + + + + + A request to retrieve a particular URI. + + + + + + + + + + + + + + + + + + Gets the length of the data represented by @request. For most +request types, this will not be known until after you call +soup_request_send() or soup_request_send_finish(). + + + the length of the data represented by @request, + or -1 if not known. + + + + + a #SoupRequest + + + + + + Gets the type of the data represented by @request. For most request +types, this will not be known until after you call +soup_request_send() or soup_request_send_finish(). + +As in the HTTP Content-Type header, this may include parameters +after the MIME type. + + + the type of the data represented by + @request, or %NULL if not known. + + + + + a #SoupRequest + + + + + + Synchronously requests the URI pointed to by @request, and returns +a #GInputStream that can be used to read its contents. + +Note that you cannot use this method with #SoupRequests attached to +a #SoupSessionAsync. + + + a #GInputStream that can be used to + read from the URI pointed to by @request. + + + + + a #SoupRequest + + + + a #GCancellable or %NULL + + + + + + Begins an asynchronously request for the URI pointed to by +@request. + +Note that you cannot use this method with #SoupRequests attached to +a #SoupSessionSync. + + + + + + + a #SoupRequest + + + + a #GCancellable or %NULL + + + + a #GAsyncReadyCallback + + + + user data passed to @callback + + + + + + Gets the result of a soup_request_send_async(). + + + a #GInputStream that can be used to + read from the URI pointed to by @request. + + + + + a #SoupRequest + + + + the #GAsyncResult + + + + + + Gets the length of the data represented by @request. For most +request types, this will not be known until after you call +soup_request_send() or soup_request_send_finish(). + + + the length of the data represented by @request, + or -1 if not known. + + + + + a #SoupRequest + + + + + + Gets the type of the data represented by @request. For most request +types, this will not be known until after you call +soup_request_send() or soup_request_send_finish(). + +As in the HTTP Content-Type header, this may include parameters +after the MIME type. + + + the type of the data represented by + @request, or %NULL if not known. + + + + + a #SoupRequest + + + + + + Gets @request's #SoupSession + + + @request's #SoupSession + + + + + a #SoupRequest + + + + + + Gets @request's URI + + + @request's URI + + + + + a #SoupRequest + + + + + + Synchronously requests the URI pointed to by @request, and returns +a #GInputStream that can be used to read its contents. + +Note that you cannot use this method with #SoupRequests attached to +a #SoupSessionAsync. + + + a #GInputStream that can be used to + read from the URI pointed to by @request. + + + + + a #SoupRequest + + + + a #GCancellable or %NULL + + + + + + Begins an asynchronously request for the URI pointed to by +@request. + +Note that you cannot use this method with #SoupRequests attached to +a #SoupSessionSync. + + + + + + + a #SoupRequest + + + + a #GCancellable or %NULL + + + + a #GAsyncReadyCallback + + + + user data passed to @callback + + + + + + Gets the result of a soup_request_send_async(). + + + a #GInputStream that can be used to + read from the URI pointed to by @request. + + + + + a #SoupRequest + + + + the #GAsyncResult + + + + + + The request's #SoupSession. + + + + The request URI. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GInputStream that can be used to + read from the URI pointed to by @request. + + + + + a #SoupRequest + + + + a #GCancellable or %NULL + + + + + + + + + + + + + + a #SoupRequest + + + + a #GCancellable or %NULL + + + + a #GAsyncReadyCallback + + + + user data passed to @callback + + + + + + + + + + a #GInputStream that can be used to + read from the URI pointed to by @request. + + + + + a #SoupRequest + + + + the #GAsyncResult + + + + + + + + + + the length of the data represented by @request, + or -1 if not known. + + + + + a #SoupRequest + + + + + + + + + + the type of the data represented by + @request, or %NULL if not known. + + + + + a #SoupRequest + + + + + + + + + + + + + + + + + + + + + + + + + + + A #SoupRequest error. + + the URI could not be parsed + + + the URI scheme is not + supported by this #SoupSession + + + the server's response could not + be parsed + + + the server's response was in an + unsupported format + + + + + + + + + + + + Gets a #GFile corresponding to @file's URI + + + a #GFile corresponding to @file + + + + + a #SoupRequestFile + + + + + + + + + + + + + + + + + + + + + + + + + Gets a new reference to the #SoupMessage associated to this SoupRequest + + + a new reference to the #SoupMessage + + + + + a #SoupRequestHTTP object + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupServer:add-websocket-extension property, qv. + + + + + Alias for the deprecated #SoupServer:async-context +property, qv. + The new API uses the thread-default #GMainContext +rather than having an explicitly-specified one. + + + + + + + + + + + + + + + + + + + Alias for the #SoupServer:https-aliases property, qv. + + + + + Alias for the #SoupServer:http-aliases property, qv. + + + + + Alias for the #SoupServer:interface property, qv. + #SoupServers can listen on multiple interfaces +at once now. Use soup_server_listen(), etc, to listen on an +interface, and soup_server_get_uris() to see what addresses +are being listened on. + + + + + Alias for the deprecated #SoupServer:port property, qv. + #SoupServers can listen on multiple interfaces +at once now. Use soup_server_listen(), etc, to listen on a +port, and soup_server_get_uris() to see what ports are +being listened on. + + + + + Alias for the #SoupServer:raw-paths property. (If %TRUE, +percent-encoding in the Request-URI path will not be +automatically decoded.) + + + + + Alias for the #SoupServer:remove-websocket-extension property, qv. + + + + + Alias for the #SoupServer:server-header property, qv. + + + + + Alias for the #SoupServer:ssl-cert-file property, qv. + use #SoupServer:tls-certificate or +soup_server_set_ssl_certificate(). + + + + + Alias for the #SoupServer:ssl-key-file property, qv. + use #SoupServer:tls-certificate or +soup_server_set_ssl_certificate(). + + + + + Alias for the #SoupServer:tls-certificate property, qv. + + + + + + + + + + + + Alias for the #SoupSession:accept-language property, qv. + + + + + Alias for the #SoupSession:accept-language-auto property, qv. + + + + + Alias for the #SoupSession:add-feature property, qv. + + + + + Alias for the #SoupSession:add-feature-by-type property, qv. + + + + + + + + + + + + + + + + + + + Alias for the #SoupSession:async-context property, qv. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupSession:https-aliases property, qv. + + + + + Alias for the #SoupSession:http-aliases property, qv. + + + + + Alias for the #SoupSession:idle-timeout property, qv. + + + + + Alias for the #SoupSession:local-address property, qv. + + + + + Alias for the #SoupSession:max-conns property, qv. + + + + + Alias for the #SoupSession:max-conns-per-host property, qv. + + + + + Alias for the #SoupSession:proxy-resolver property, qv. + + + + + Alias for the #SoupSession:proxy-uri property, qv. + + + + + Alias for the #SoupSession:remove-feature-by-type property, +qv. + + + + + Alias for the #SoupSession:ssl-ca-file property, qv. + + + + + Alias for the #SoupSession:ssl-strict property, qv. + + + + + Alias for the #SoupSession:ssl-use-system-ca-file property, +qv. + + + + + + + + + + + + + + + + + + + + + + + + + + Alias for the #SoupSession:timeout property, qv. + + + + + Alias for the #SoupSession:tls-database property, qv. + + + + + Alias for the #SoupSession:tls-interaction property, qv. + + + + + Alias for the #SoupSession:user-agent property, qv. + + + + + Alias for the #SoupSession:use-ntlm property, qv. + + + + + Alias for the #SoupSession:use-thread-context property, qv. + + + + + + + + + + + + Alias for the #SoupSocket:async-context property. (The +socket's #GMainContext.) + + + + + + + + + + + + Alias for the #SoupSocket:non-blocking property. (Whether +or not the socket uses non-blocking I/O.) + + + + + + + + + + + + Alias for the #SoupSocket:is-server property, qv. + + + + + Alias for the #SoupSocket:local-address property. (Address +of local end of socket.) + + + + + Alias for the #SoupSocket:remote-address property. (Address +of remote end of socket.) + + + + + Alias for the #SoupSocket:ssl-creds property. +(SSL credential information.) + + + + + Alias for the #SoupSocket:ssl-fallback property. + + + + + Alias for the #SoupSocket:ssl-strict property. + + + + + Alias for the #SoupSocket:timeout property. (The timeout +in seconds for blocking socket I/O operations.) + + + + + Alias for the #SoupSocket:tls-certificate +property. Note that this property's value is only useful +if the socket is for a TLS connection, and only reliable +after some data has been transferred to or from it. + + + + + Alias for the #SoupSocket:tls-errors +property. Note that this property's value is only useful +if the socket is for a TLS connection, and only reliable +after some data has been transferred to or from it. + + + + + Alias for the #SoupSocket:trusted-certificate +property. + + + + + Alias for the #SoupSocket:use-thread-context property. (Use +g_main_context_get_thread_default()) + + + + + 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 + + + + + Tests if @status is a libsoup transport error. + + + + a status code + + + + + + + Creates a new #SoupServer. This is exactly equivalent to calling +g_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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Add 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 +"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 under @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 #SoupAuthDomain or a signal handler), @callback +will be invoked after receiving the request headers, but before +receiving the request body; the message's #SoupMessage:method and +#SoupMessage:request-headers fields will be filled in. + +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 +soup_message_body_set_accumulate() on the message's +#SoupMessage:request-body to turn off request-body accumulation, +and connect to the message's #SoupMessage::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 #SoupMessage::got-body, +or else you can register a non-early handler for @path as well. As +long as you have not set the #SoupMessage:status-code by the time +#SoupMessage::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 under @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 #SoupAuthDomain, an early #SoupServerHandler, or a +signal handler), @callback will be invoked after receiving the +request body; the message's #SoupMessage:method, +#SoupMessage:request-headers, and #SoupMessage:request-body fields +will be filled in. + +After determining what to do with the request, the callback must at +a minimum call soup_message_set_status() (or +soup_message_set_status_full()) 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 soup_server_pause_message() +to tell @server to not send the response right away. When the +response is ready, call soup_server_unpause_message() to cause it +to be sent. + +To send the response body a bit at a time using "chunked" encoding, +first call soup_message_headers_set_encoding() to set +%SOUP_ENCODING_CHUNKED on the #SoupMessage:response-headers. Then call +soup_message_body_append() (or soup_message_body_append_buffer()) +to append each chunk as it becomes ready, and +soup_server_unpause_message() 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 +soup_message_body_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 #SoupWebsocketExtension of type @extension_type will be created +to handle the request. + +You can also add support for a WebSocket extension to the server at +construct time by using the %SOUP_SERVER_ADD_WEBSOCKET_EXTENSION property. +Note that #SoupWebsocketExtensionDeflate is supported by default, use +soup_server_remove_websocket_extension() if you want to disable it. + + + + + + + a #SoupServer + + + + a #GType + + + + + + Adds a WebSocket handler to @server for requests under @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 (possibly calling +soup_server_check_websocket_handshake() one or more times), 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. If you are using the +old #SoupServer APIs, this also includes the effect of +soup_server_quit(). + +Note that if there are currently requests in progress on @server, +that they will continue to be processed if @server's #GMainContext +is still running. + +You can call soup_server_listen(), etc, after calling this function +if you want to start listening again. + + + + + + + a #SoupServer + + + + + + Gets @server's async_context, if you are using the old API. (With +the new API, the server runs in the thread's thread-default +#GMainContext, regardless of what this method returns.) + +This does not add a ref to the context, so you will need to ref it +yourself if you want it to outlive its server. + If you are using soup_server_listen(), etc, then +the server listens on the thread-default #GMainContext, and this +property is ignored. + + + @server's #GMainContext, +which may be %NULL + + + + + a #SoupServer + + + + + + Gets @server's listening socket, if you are using the old API. + +You should treat this socket as read-only; writing to it or +modifiying it may cause @server to malfunction. + If you are using soup_server_listen(), etc, then use +soup_server_get_listeners() to get a list of all listening sockets, +but note that that function returns #GSockets, not #SoupSockets. + + + the listening socket. + + + + + 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. + +(Beware that in contrast to the old soup_server_get_listener(), this +function returns #GSockets, not #SoupSockets.) + + + a +list of listening sockets. + + + + + + + a #SoupServer + + + + + + Gets the TCP port that @server is listening on, if you are using +the old API. + If you are using soup_server_listen(), etc, then use +soup_server_get_uris() to get a list of all listening addresses. + + + the port @server is listening on. + + + + + 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 soup_server_listen_all(), the returned URIs +will use the addresses <literal>0.0.0.0</literal> and +<literal>::</literal>, rather than actually returning separate URIs +for each interface on the system. + + + a list of +#SoupURIs, which you must free 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 +soup_server_set_ssl_cert_file(), or set the +#SoupServer: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 #SoupServer serves https +exclusively. If you are using soup_server_listen(), etc, then a +%TRUE return value merely indicates that the server is +<emphasis>able</emphasis> to do https, regardless of whether it +actually currently is or not. Use soup_server_get_uris() to see if +it currently has any https listeners. + + + %TRUE if @server is configured to serve https. + + + + + a #SoupServer + + + + + + This 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 #GMainContext is +run. + +Note that #SoupServer never makes 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 + + + + + + This attempts to set up @server to listen for connections on all +interfaces on the system. (That is, it listens on the addresses +<literal>0.0.0.0</literal> and/or <literal>::</literal>, 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 +soup_server_get_uris() to find out what port it ended up choosing.) + +See soup_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 + + + + + + This attempts to set up @server to listen for connections on +@fd. + +See soup_server_listen() for more details. + +Note that @server will close @fd when you free it or call +soup_server_disconnect(). + + + %TRUE on success, %FALSE if an error occurred (in +which case @error will be set). + + + + + a #SoupServer + + + + the file descriptor of a listening socket + + + + listening options for this server + + + + + + This attempts to set up @server to listen for connections on +"localhost" (that is, <literal>127.0.0.1</literal> and/or +<literal>::1</literal>, 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 soup_server_get_uris() to find out what port it +ended up choosing.) + +See soup_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 + + + + + + This attempts to set up @server to listen for connections on +@socket. + +See soup_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 +soup_server_unpause_message() to resume I/O. + +This must only be called on #SoupMessages which were created by the +#SoupServer and are currently doing I/O, such as those passed into a +#SoupServerCallback or emitted in a #SoupServer::request-read signal. + + + + + + + a #SoupServer + + + + a #SoupMessage associated with @server. + + + + + + Stops processing for @server, if you are using the old API. Call +this to clean up after soup_server_run_async(), or to terminate a +call to soup_server_run(). + +Note that messages currently in progress will continue to be +handled, if the main loop associated with the server is resumed or +kept running. + +@server is still in a working state after this call; you can start +and stop a server as many times as you want. + When using soup_server_listen(), etc, the server will +always listen for connections, and will process them whenever the +thread-default #GMainContext is running. + + + + + + + a #SoupServer + + + + + + 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. You can also remove extensions enabled by default +from the server at construct time by using the %SOUP_SERVER_REMOVE_WEBSOCKET_EXTENSION +property. + + + + + + + a #SoupServer + + + + a #GType + + + + + + Starts @server, if you are using the old API, causing it to listen +for and process incoming connections. Unlike +soup_server_run_async(), this creates a #GMainLoop and runs it, and +it will not return until someone calls soup_server_quit() to stop +the server. + When using soup_server_listen(), etc, the server will +always listen for connections, and will process them whenever the +thread-default #GMainContext is running. + + + + + + + a #SoupServer + + + + + + Starts @server, if you are using the old API, causing it to listen +for and process incoming connections. + +The server runs in @server's #GMainContext. It will not actually +perform any processing unless the appropriate main loop is running. +In the simple case where you did not set the server's +%SOUP_SERVER_ASYNC_CONTEXT property, this means the server will run +whenever the glib main loop is running. + When using soup_server_listen(), etc, the server will +always listen for connections, and will process them whenever the +thread-default #GMainContext is running. + + + + + + + a #SoupServer + + + + + + Sets @server up to do https, using the SSL/TLS certificate +specified by @ssl_cert_file and @ssl_key_file (which may point to +the same file). + +Alternatively, you can set the #SoupServer:tls-certificate property +at construction time, if you already have a #GTlsCertificate. + + + success or failure. + + + + + a #SoupServer + + + + path to a file containing a PEM-encoded SSL/TLS + certificate. + + + + path to a file containing a PEM-encoded private key. + + + + + + Resumes I/O on @msg. Use this to resume after calling +soup_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 #SoupMessages which were created by the +#SoupServer and are currently doing I/O, such as those passed into a +#SoupServerCallback or emitted in a #SoupServer::request-read signal. + + + + + + + a #SoupServer + + + + a #SoupMessage associated with @server. + + + + + + Add support for #SoupWebsocketExtension of the given type. +(Shortcut for calling soup_server_add_websocket_extension().) + + + + The server's #GMainContext, if you are using the old API. +Servers created using soup_server_listen() will listen on +the #GMainContext that was the thread-default context at +the time soup_server_listen() was called. + The new API uses the thread-default #GMainContext +rather than having an explicitly-specified one. + + + + A %NULL-terminated array of URI schemes that should be +considered to be aliases for "http". Eg, if this included +<literal>"dav"</literal>, than a URI of +<literal>dav://example.com/path</literal> would be treated +identically to <literal>http://example.com/path</literal>. +In particular, this is needed in cases where a client +sends requests with absolute URIs, where those URIs do +not use "http:". + +The default value is an array containing the single element +<literal>"*"</literal>, a special value which means that +any scheme except "https" is considered to be an alias for +"http". + +See also #SoupServer:https-aliases. + + + + + + A comma-delimited list of URI schemes that should be +considered to be aliases for "https". See +#SoupServer:http-aliases for more information. + +The default value is %NULL, meaning that no URI schemes +are considered aliases for "https". + + + + + + The address of the network interface the server is +listening on, if you are using the old #SoupServer API. +(This will not be set if you use soup_server_listen(), +etc.) + #SoupServers can listen on multiple interfaces +at once now. Use soup_server_listen(), etc, to listen on an +interface, and soup_server_get_uris() to see what addresses +are being listened on. + + + + The port the server is listening on, if you are using the +old #SoupServer API. (This will not be set if you use +soup_server_listen(), etc.) + #SoupServers can listen on multiple interfaces +at once now. Use soup_server_listen(), etc, to listen on a +port, and soup_server_get_uris() to see what ports are +being listened on. + + + + + + + Remove support for #SoupWebsocketExtension of the given type. (Shortcut for +calling soup_server_remove_websocket_extension().) + + + + If non-%NULL, the value to use for the "Server" header on +#SoupMessage<!-- -->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 #SoupSession:user_agent, if you set a +#SoupServer:server_header property that has trailing whitespace, +#SoupServer will append its own product token (eg, +"<literal>libsoup/2.3.2</literal>") to the end of the +header for you. + + + + Path to a file containing a PEM-encoded certificate. + +If you set this property and #SoupServer:ssl-key-file at +construct time, then soup_server_new() will try to read the +files; if it cannot, it will return %NULL, with no explicit +indication of what went wrong (and logging a warning with +newer versions of glib, since returning %NULL from a +constructor is illegal). + use #SoupServer:tls-certificate or +soup_server_set_ssl_certificate(). + + + + Path to a file containing a PEM-encoded private key. See +#SoupServer:ssl-cert-file for more information about how this +is used. + use #SoupServer:tls-certificate or +soup_server_set_ssl_certificate(). + + + + A #GTlsCertificate that has a #GTlsCertificate:private-key +set. If this is set, then the server will be able to speak +https in addition to (or instead of) plain http. + +Alternatively, you can call soup_server_set_ssl_cert_file() +to have #SoupServer read in a a certificate from a file. + + + + + + + Emitted when processing has failed for a message; this +could mean either that it could not be read (if +#SoupServer::request_read has not been emitted for it yet), +or that the response could not be written back (if +#SoupServer::request_read has been emitted but +#SoupServer::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 +#SoupServer::request_started. + + + + + + the message + + + + the client context + + + + + + Emitted when the server has finished writing a response to +a request. + + + + + + the message + + + + the client context + + + + + + 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 + + + + the client context + + + + + + 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 #SoupServer::request_read signal. If a +response is then sent, the request processing will end with +a #SoupServer::request_finished signal. If a network error +occurs, the processing will instead end with +#SoupServer::request_aborted. + + + + + + the new message + + + + the client context + + + + + + + A callback used to handle requests to a #SoupServer. + +@path and @query contain the likewise-named components of the +Request-URI, subject to certain assumptions. By default, +#SoupServer 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 %SOUP_SERVER_RAW_PATHS property when creating +the #SoupServer, and it will leave those characters undecoded. (You +may want to call soup_uri_normalize() to decode any percent-encoded +characters that you aren't handling specially.) + +@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 soup_message_get_uri() and parse the URI's query field +yourself. + +See soup_server_add_handler() and soup_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 + + + + + + + additional contextual information about the client + + + + the data passed to soup_server_add_handler() or + soup_server_add_early_handler(). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Options to pass to soup_server_listen(), etc. + +%SOUP_SERVER_LISTEN_IPV4_ONLY and %SOUP_SERVER_LISTEN_IPV6_ONLY +only make sense with soup_server_listen_all() and +soup_server_listen_local(), not plain soup_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. + + + + A callback used to handle WebSocket requests to a #SoupServer. 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 #SoupServerCallback (qv). + + + + + + + the #SoupServer + + + + the newly created WebSocket connection + + + + the path component of @msg's Request-URI + + + + additional contextual information about the client + + + + the data passed to @soup_server_add_handler + + + + + + + + Creates a #SoupSession with the default options. + + + the new session. + + + + + Creates a #SoupSession with the specified options. + + + the new session. + + + + + name of first property to set + + + + value of @optname1, followed by additional property/value pairs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Causes @session to immediately finish processing @msg (regardless +of its current state) with a final status_code of @status_code. You +may call this at any time after handing @msg off to @session; if +@session has started sending the request but has not yet received +the complete response, then it will close the request's connection. +Note that with requests that have side effects (eg, +<literal>POST</literal>, <literal>PUT</literal>, +<literal>DELETE</literal>) 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 the message is cancelled while its response body is being read, +then the response body in @msg will be left partially-filled-in. +The response headers, on the other hand, will always be either +empty or complete. + +Beware that with the deprecated #SoupSessionAsync, messages queued +with soup_session_queue_message() will have their callbacks invoked +before soup_session_cancel_message() returns. The plain +#SoupSession does not have this behavior; cancelling an +asynchronous message will merely queue its callback to be run after +returning to the main loop. + + + + + + + a #SoupSession + + + + the message to cancel + + + + status code to set on @msg (generally +%SOUP_STATUS_CANCELLED) + + + + + + + + + + + + + + + + + + + + + + + + + + + + Queues the message @msg for asynchronously sending the request and +receiving a response in the current thread-default #GMainContext. +If @msg has been processed before, any resources related to the +time it was last sent are freed. + +Upon message completion, the callback specified in @callback will +be invoked. If after returning from this callback the message has not +been requeued, @msg will be unreffed. + +(The behavior above applies to a plain #SoupSession; if you are +using #SoupSessionAsync or #SoupSessionSync, then the #GMainContext +that is used depends on the settings of #SoupSession:async-context +and #SoupSession:use-thread-context, and for #SoupSessionSync, the +message will actually be sent and processed in another thread, with +only the final callback occurring in the indicated #GMainContext.) + +Contrast this method with soup_session_send_async(), which also +asynchronously sends a message, but returns before reading the +response body, and allows you to read the response via a +#GInputStream. + + + + + + + a #SoupSession + + + + the message to queue + + + + a #SoupSessionCallback which will +be called after the message completes or when an unrecoverable error occurs. + + + + a pointer passed to @callback. + + + + + + + + + + + + + + + + + + + + + + + This causes @msg to be placed back on the queue to be attempted +again. + + + + + + + a #SoupSession + + + + the message to requeue + + + + + + Synchronously send @msg. This call will not return until the +transfer is finished successfully or there is an unrecoverable +error. + +Unlike with soup_session_queue_message(), @msg is not freed upon +return. + +(Note that if you call this method on a #SoupSessionAsync, it will +still use asynchronous I/O internally, running the glib main loop +to process the message, which may also cause other events to be +processed.) + +Contrast this method with soup_session_send(), which also +synchronously sends a message, but returns before reading the +response body, and allows you to read the response via a +#GInputStream. + + + the HTTP status code of the response + + + + + a #SoupSession + + + + the message to send + + + + + + Cancels all pending requests in @session and closes all idle +persistent connections. + +The message cancellation has the same semantics as with +soup_session_cancel_message(); asynchronous requests on a +#SoupSessionAsync will have their callback called before +soup_session_abort() returns. Requests on a plain #SoupSession will +not. + + + + + + + the session + + + + + + Adds @feature's functionality to @session. You can also add a +feature to the session at construct time by using the +%SOUP_SESSION_ADD_FEATURE property. + +See the main #SoupSession 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 +#SoupSessionFeature, this creates a new feature of that type and +adds it to @session as with soup_session_add_feature(). You can use +this when you don't need to customize the new feature in any way. + +If @feature_type is not a #SoupSessionFeature type, this gives each +existing feature on @session the chance to accept @feature_type as +a "subfeature". This can be used to add new #SoupAuth or +#SoupRequest types, for instance. + +You can also add a feature to the session at construct time by +using the %SOUP_SESSION_ADD_FEATURE_BY_TYPE property. + +See the main #SoupSession documentation for information on what +features are present in sessions by default. + + + + + + + a #SoupSession + + + + a #GType + + + + + + Causes @session to immediately finish processing @msg (regardless +of its current state) with a final status_code of @status_code. You +may call this at any time after handing @msg off to @session; if +@session has started sending the request but has not yet received +the complete response, then it will close the request's connection. +Note that with requests that have side effects (eg, +<literal>POST</literal>, <literal>PUT</literal>, +<literal>DELETE</literal>) 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 the message is cancelled while its response body is being read, +then the response body in @msg will be left partially-filled-in. +The response headers, on the other hand, will always be either +empty or complete. + +Beware that with the deprecated #SoupSessionAsync, messages queued +with soup_session_queue_message() will have their callbacks invoked +before soup_session_cancel_message() returns. The plain +#SoupSession does not have this behavior; cancelling an +asynchronous message will merely queue its callback to be run after +returning to the main loop. + + + + + + + a #SoupSession + + + + the message to cancel + + + + status code to set on @msg (generally +%SOUP_STATUS_CANCELLED) + + + + + + Start a connection to @uri. The operation can be monitored by providing a @progress_callback +and finishes when the connection is done or an error ocurred. + +Call soup_session_connect_finish() to get the #GIOStream to communicate with the server. + + + + + + + a #SoupSession + + + + a #SoupURI to connect to + + + + a #GCancellable + + + + a #SoupSessionConnectProgressCallback which +will be called for every network event that occurs during the connection. + + + + the callback to invoke when the operation finishes + + + + data for @progress_callback and @callback + + + + + + Gets the #GIOStream created for the connection to communicate with the server. + + + a new #GIOStream, or %NULL on error. + + + + + a #SoupSession + + + + the #GAsyncResult passed to your callback + + + + + + Gets @session's #SoupSession:async-context. This does not add a ref +to the context, so you will need to ref it yourself if you want it +to outlive its session. + +For a modern #SoupSession, this will always just return the +thread-default #GMainContext, and so is not especially useful. + + + @session's #GMainContext, +which may be %NULL + + + + + a #SoupSession + + + + + + Gets the first feature in @session of type @feature_type. For +features where there may be more than one feature of a given type, +use soup_session_get_features(). + + + a #SoupSessionFeature, or +%NULL. The feature is owned by @session. + + + + + a #SoupSession + + + + the #GType of the feature to get + + + + + + Gets the first feature in @session of type @feature_type, provided +that it is not disabled for @msg. As with +soup_session_get_feature(), this should only be used for features +where @feature_type is only expected to match a single feature. In +particular, if there are two matching features, and the first is +disabled on @msg, and the second is not, then this will return +%NULL, not the second feature. + + + a #SoupSessionFeature, or %NULL. The +feature is owned by @session. + + + + + a #SoupSession + + + + the #GType of the feature to get + + + + a #SoupMessage + + + + + + Generates a list of @session's features of type @feature_type. (If +you want to see all features, you can pass %SOUP_TYPE_SESSION_FEATURE +for @feature_type.) + + + +a list of features. You must free the list, but not its contents + + + + + + + a #SoupSession + + + + the #GType of the class of features to get + + + + + + Tests if @session has at a feature of type @feature_type (which can +be the type of either a #SoupSessionFeature, or else a subtype of +some class managed by another feature, such as #SoupAuth or +#SoupRequest). + + + %TRUE or %FALSE + + + + + a #SoupSession + + + + the #GType of the class of features to check for + + + + + + Pauses HTTP I/O on @msg. Call soup_session_unpause_message() to +resume I/O. + +This may only be called for asynchronous messages (those sent on a +#SoupSessionAsync or using soup_session_queue_message()). + + + + + + + a #SoupSession + + + + a #SoupMessage currently running on @session + + + + + + Tells @session that an URI from the given @hostname may be requested +shortly, and so the session can try to prepare by resolving the +domain name in advance, in order to work more quickly once the URI +is actually requested. + +If @cancellable is non-%NULL, it can be used to cancel the +resolution. @callback will still be invoked in this case, with a +status of %SOUP_STATUS_CANCELLED. + + + + + + + a #SoupSession + + + + a hostname to be resolved + + + + a #GCancellable object, or %NULL + + + + callback to call with the + result, or %NULL + + + + data for @callback + + + + + + Tells @session that @uri may be requested shortly, and so the +session can try to prepare (resolving the domain name, obtaining +proxy address, etc.) in order to work more quickly once the URI is +actually requested. + use soup_session_prefetch_dns() instead + + + + + + + a #SoupSession + + + + a #SoupURI which may be required + + + + + + Queues the message @msg for asynchronously sending the request and +receiving a response in the current thread-default #GMainContext. +If @msg has been processed before, any resources related to the +time it was last sent are freed. + +Upon message completion, the callback specified in @callback will +be invoked. If after returning from this callback the message has not +been requeued, @msg will be unreffed. + +(The behavior above applies to a plain #SoupSession; if you are +using #SoupSessionAsync or #SoupSessionSync, then the #GMainContext +that is used depends on the settings of #SoupSession:async-context +and #SoupSession:use-thread-context, and for #SoupSessionSync, the +message will actually be sent and processed in another thread, with +only the final callback occurring in the indicated #GMainContext.) + +Contrast this method with soup_session_send_async(), which also +asynchronously sends a message, but returns before reading the +response body, and allows you to read the response via a +#GInputStream. + + + + + + + a #SoupSession + + + + the message to queue + + + + a #SoupSessionCallback which will +be called after the message completes or when an unrecoverable error occurs. + + + + a pointer passed to @callback. + + + + + + Updates @msg's URI according to its status code and "Location" +header, and requeues it on @session. Use this when you have set +%SOUP_MESSAGE_NO_REDIRECT on a message, but have decided to allow a +particular redirection to occur, or if you want to allow a +redirection that #SoupSession will not perform automatically (eg, +redirecting a non-safe method such as DELETE). + +If @msg's status code indicates that it should be retried as a GET +request, then @msg will be modified accordingly. + +If @msg has already been redirected too many times, this will +cause it to fail with %SOUP_STATUS_TOO_MANY_REDIRECTS. + + + %TRUE if a redirection was applied, %FALSE if not +(eg, because there was no Location header, or it could not be +parsed). + + + + + the session + + + + a #SoupMessage that has received a 3xx response + + + + + + 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. You can also remove standard features +from the session at construct time by using the +%SOUP_SESSION_REMOVE_FEATURE_BY_TYPE property. + + + + + + + a #SoupSession + + + + a #GType + + + + + + Creates a #SoupRequest for retrieving @uri_string. + + + a new #SoupRequest, or + %NULL on error. + + + + + a #SoupSession + + + + a URI, in string form + + + + + + Creates a #SoupRequest for retrieving @uri_string, which must be an +"http" or "https" URI (or another protocol listed in @session's +#SoupSession:http-aliases or #SoupSession:https-aliases). + + + a new #SoupRequestHTTP, or + %NULL on error. + + + + + a #SoupSession + + + + an HTTP method + + + + a URI, in string form + + + + + + Creates a #SoupRequest for retrieving @uri, which must be an +"http" or "https" URI (or another protocol listed in @session's +#SoupSession:http-aliases or #SoupSession:https-aliases). + + + a new #SoupRequestHTTP, or + %NULL on error. + + + + + a #SoupSession + + + + an HTTP method + + + + a #SoupURI representing the URI to retrieve + + + + + + Creates a #SoupRequest for retrieving @uri. + + + a new #SoupRequest, or + %NULL on error. + + + + + a #SoupSession + + + + a #SoupURI representing the URI to retrieve + + + + + + This causes @msg to be placed back on the queue to be attempted +again. + + + + + + + a #SoupSession + + + + the message to requeue + + + + + + Synchronously sends @msg and waits for the beginning of a response. +On success, a #GInputStream 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; +soup_session_send() will return a %G_IO_ERROR_CANCELLED error. Note +that with requests that have side effects (eg, +<literal>POST</literal>, <literal>PUT</literal>, +<literal>DELETE</literal>) 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 +soup_session_send() will only return once a final response has been +received. + +Contrast this method with soup_session_send_message(), which also +synchronously sends a #SoupMessage, but doesn't return until the +response has been completely read. + +(Note that this method cannot be called on the deprecated +#SoupSessionAsync subclass.) + + + a #GInputStream for reading the + response body, or %NULL on error. + + + + + a #SoupSession + + + + a #SoupMessage + + + + a #GCancellable + + + + + + 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 soup_session_send_finish() to get a #GInputStream for reading +the response body. + +See soup_session_send() for more details on the general semantics. + +Contrast this method with soup_session_queue_message(), which also +asynchronously sends a #SoupMessage, but doesn't invoke its +callback until the response has been completely read. + +(Note that this method cannot be called on the deprecated +#SoupSessionSync subclass, and can only be called on +#SoupSessionAsync if you have set the +#SoupSession:use-thread-context property.) + + + + + + + a #SoupSession + + + + a #SoupMessage + + + + a #GCancellable + + + + the callback to invoke + + + + data for @callback + + + + + + Gets the response to a soup_session_send_async() call and (if +successful), returns a #GInputStream 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 + + + + + + Synchronously send @msg. This call will not return until the +transfer is finished successfully or there is an unrecoverable +error. + +Unlike with soup_session_queue_message(), @msg is not freed upon +return. + +(Note that if you call this method on a #SoupSessionAsync, it will +still use asynchronous I/O internally, running the glib main loop +to process the message, which may also cause other events to be +processed.) + +Contrast this method with soup_session_send(), which also +synchronously sends a message, but returns before reading the +response body, and allows you to read the response via a +#GInputStream. + + + the HTTP status code of the response + + + + + a #SoupSession + + + + the message to send + + + + + + "Steals" the HTTP connection associated with @msg from @session. +This happens immediately, regardless of the current state of the +connection, and @msg's callback will not be called. You can steal +the connection from a #SoupMessage signal handler if you need to +wait for part or all of the response to be received first. + +Calling this function may cause @msg to be freed if you are not +holding any other reference to it. + + + 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 #SoupSession + + + + the message whose connection is to be stolen + + + + + + Resumes HTTP I/O on @msg. Use this to resume after calling +soup_session_pause_message(). + +If @msg is being sent via blocking I/O, this will resume reading or +writing immediately. If @msg is using non-blocking I/O, then +reading or writing won't resume until you return to the main loop. + +This may only be called for asynchronous messages (those sent on a +#SoupSessionAsync or using soup_session_queue_message()). + + + + + + + a #SoupSession + + + + a #SoupMessage currently running on @session + + + + + + Asynchronously creates a #SoupWebsocketConnection 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, +soup_session_websocket_connect_finish() will return a new +#SoupWebsocketConnection. 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 +soup_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 + + + + + + a #GCancellable + + + + the callback to invoke + + + + data for @callback + + + + + + Gets the #SoupWebsocketConnection response to a +soup_session_websocket_connect_async() call and (if successful), +returns a #SoupWebsocketConnection that can be used to communicate +with the server. + + + a new #SoupWebsocketConnection, or + %NULL on error. + + + + + a #SoupSession + + + + the #GAsyncResult passed to your callback + + + + + + Checks if @msg contains a response that would cause @session to +redirect it to a new URL (ignoring @msg's %SOUP_MESSAGE_NO_REDIRECT +flag, and the number of times it has already been redirected). + + + whether @msg would be redirected + + + + + a #SoupSession + + + + a #SoupMessage that has response headers + + + + + + If non-%NULL, the value to use for the "Accept-Language" header +on #SoupMessage<!-- -->s sent from this session. + +Setting this will disable +#SoupSession:accept-language-auto. + + + + If %TRUE, #SoupSession will automatically set the string +for the "Accept-Language" header on every #SoupMessage +sent, based on the return value of g_get_language_names(). + +Setting this will override any previous value of +#SoupSession:accept-language. + + + + Add a feature object to the session. (Shortcut for calling +soup_session_add_feature().) + + + + Add a feature object of the given type to the session. +(Shortcut for calling soup_session_add_feature_by_type().) + + + + The #GMainContext that miscellaneous session-related +asynchronous callbacks are invoked on. (Eg, setting +#SoupSession:idle-timeout will add a timeout source on this +context.) + +For a plain #SoupSession, this property is always set to +the #GMainContext that is the thread-default at the time +the session was created, and cannot be overridden. For the +deprecated #SoupSession subclasses, the default value is +%NULL, meaning to use the global default #GMainContext. + +If #SoupSession:use-thread-context is %FALSE, this context +will also be used for asynchronous HTTP I/O. + + + + A %NULL-terminated array of URI schemes that should be +considered to be aliases for "http". Eg, if this included +<literal>"dav"</literal>, than a URI of +<literal>dav://example.com/path</literal> would be treated +identically to <literal>http://example.com/path</literal>. + +In a plain #SoupSession, the default value is %NULL, +meaning that only "http" is recognized as meaning "http". +In #SoupSessionAsync and #SoupSessionSync, for backward +compatibility, the default value is an array containing the +single element <literal>"*"</literal>, a special value +which means that any scheme except "https" is considered to +be an alias for "http". + +See also #SoupSession:https-aliases. + + + + + + A comma-delimited list of URI schemes that should be +considered to be aliases for "https". See +#SoupSession:http-aliases for more information. + +The default value is %NULL, meaning that no URI schemes +are considered aliases for "https". + + + + + + 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 soup_session_abort() after setting this +if you want to ensure that all future connections will have +this timeout value. + +Note that the default value of 60 seconds only applies to +plain #SoupSessions. If you are using #SoupSessionAsync or +#SoupSessionSync, the default value is 0 (meaning idle +connections will never time out). + + + + Sets the #SoupAddress 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. + + + + + + + + + + A #GProxyResolver to use with this session. Setting this +will clear the #SoupSession:proxy-uri property, and remove +any <type>SoupProxyURIResolver</type> features that have +been added to the session. + +By default, in a plain #SoupSession, this is set to the +default #GProxyResolver, but you can set it to %NULL if you +don't want to use proxies, or set it to your own +#GProxyResolver if you want to control what proxies get +used. + + + + A proxy to use for all http and https requests in this +session. Setting this will clear the +#SoupSession:proxy-resolver property, and remove any +<type>SoupProxyURIResolver</type> features that have been +added to the session. Setting this property will also +cancel all currently pending messages. + +Note that #SoupSession will normally handle looking up the +user's proxy settings for you; you should only use +#SoupSession:proxy-uri if you need to override the user's +normal proxy settings. + +Also note that this proxy will be used for +<emphasis>all</emphasis> requests; even requests to +<literal>localhost</literal>. If you need more control over +proxies, you can create a #GSimpleProxyResolver and set the +#SoupSession:proxy-resolver property. + + + + Remove feature objects from the session. (Shortcut for +calling soup_session_remove_feature_by_type().) + + + + File containing SSL CA certificates. + +If the specified file does not exist or cannot be read, +then libsoup will print a warning, and then behave as +though it had read in a empty CA file, meaning that all SSL +certificates will be considered invalid. + use #SoupSession:ssl-use-system-ca-file, or +else #SoupSession:tls-database with a #GTlsFileDatabase +(which allows you to do explicit error handling). + + + + Normally, if #SoupSession:tls-database is set (including if +it was set via #SoupSession:ssl-use-system-ca-file or +#SoupSession:ssl-ca-file), then libsoup will reject any +certificate that is invalid (ie, expired) or that is not +signed by one of the given CA certificates, and the +#SoupMessage will fail with the status +%SOUP_STATUS_SSL_FAILED. + +If you set #SoupSession:ssl-strict to %FALSE, then all +certificates will be accepted, and you will need to call +soup_message_get_https_status() to distinguish valid from +invalid certificates. (This can be used, eg, if you want to +accept invalid certificates after giving some sort of +warning.) + +For a plain #SoupSession, if the session has no CA file or +TLS database, and this property is %TRUE, then all +certificates will be rejected. However, beware that the +deprecated #SoupSession subclasses (#SoupSessionAsync and +#SoupSessionSync) have the opposite behavior: if there is +no CA file or TLS database, then all certificates are always +accepted, and this property has no effect. + + + + Setting this to %TRUE is equivalent to setting +#SoupSession:tls-database to the default system CA database. +(and likewise, setting #SoupSession:tls-database to the +default database by hand will cause this property to +become %TRUE). + +Setting this to %FALSE (when it was previously %TRUE) will +clear the #SoupSession:tls-database field. + +See #SoupSession:ssl-strict for more information on how +https certificate validation is handled. + +Note that the default value of %TRUE only applies to plain +#SoupSessions. If you are using #SoupSessionAsync or +#SoupSessionSync, the default value is %FALSE, for backward +compatibility. + + + + 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 soup_session_abort() after setting this +if you want to ensure that all future connections will have +this timeout value. + +Note that the default value of 60 seconds only applies to +plain #SoupSessions. If you are using #SoupSessionAsync or +#SoupSessionSync, the default value is 0 (meaning socket I/O +will not time out). + +Not to be confused with #SoupSession:idle-timeout (which is +the length of time that idle persistent connections will be +kept open). + + + + Sets the #GTlsDatabase to use for validating SSL/TLS +certificates. + +Note that setting the #SoupSession:ssl-ca-file or +#SoupSession:ssl-use-system-ca-file property will cause +this property to be set to a #GTlsDatabase corresponding to +the indicated file or system default. + +See #SoupSession:ssl-strict for more information on how +https certificate validation is handled. + +If you are using a plain #SoupSession then +#SoupSession:ssl-use-system-ca-file will be %TRUE by +default, and so this property will be a copy of the system +CA database. If you are using #SoupSessionAsync or +#SoupSessionSync, this property will be %NULL by default. + + + + A #GTlsInteraction object that will be passed on to any +#GTlsConnections created by the session. (This can be used to +provide client-side certificates, for example.) + + + + Whether or not to use NTLM authentication. + use soup_session_add_feature_by_type() with +#SOUP_TYPE_AUTH_NTLM. + + + + If %TRUE (which it always is on a plain #SoupSession), +asynchronous HTTP requests in this session will run in +whatever the thread-default #GMainContext is at the time +they are started, rather than always occurring in +#SoupSession:async-context. + + + + If non-%NULL, the value to use for the "User-Agent" header +on #SoupMessage<!-- -->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 #SoupSession:user_agent property that has trailing +whitespace, #SoupSession will append its own product token +(eg, "<literal>libsoup/2.3.2</literal>") to the end of the +header for you. + + + + + + + Emitted when the session requires authentication. If +credentials are available call soup_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 +soup_auth_authenticate() on @auth. + +Note that this may be emitted before @msg's body has been +fully read. + +If you call soup_session_pause_message() on @msg before +returning, then you can authenticate @auth asynchronously +(as long as you g_object_ref() it to make sure it doesn't +get destroyed), and then unpause @msg when you are ready +for it to continue. + + + + + + the #SoupMessage being sent + + + + the #SoupAuth to authenticate + + + + %TRUE if this is the second (or later) attempt + + + + + + Emitted when a new connection is created. This is an +internal signal intended only to be used for debugging +purposes, and may go away in the future. + + + + + + the connection + + + + + + Emitted when a request is queued on @session. (Note that +"queued" doesn't just mean soup_session_queue_message(); +soup_session_send_message() implicitly queues the message +as well.) + +When sending a request, first #SoupSession::request_queued +is emitted, indicating that the session has become aware of +the request. + +Once a connection is available to send the request on, the +session emits #SoupSession::request_started. Then, various +#SoupMessage signals are emitted as the message is +processed. If the message is requeued, it will emit +#SoupMessage::restarted, which will then be followed by +another #SoupSession::request_started and another set of +#SoupMessage signals when the message is re-sent. + +Eventually, the message will emit #SoupMessage::finished. +Normally, this signals the completion of message +processing. However, it is possible that the application +will requeue the message from the "finished" handler (or +equivalently, from the soup_session_queue_message() +callback). In that case, the process will loop back to +#SoupSession::request_started. + +Eventually, a message will reach "finished" and not be +requeued. At that point, the session will emit +#SoupSession::request_unqueued to indicate that it is done +with the message. + +To sum up: #SoupSession::request_queued and +#SoupSession::request_unqueued are guaranteed to be emitted +exactly once, but #SoupSession::request_started and +#SoupMessage::finished (and all of the other #SoupMessage +signals) may be invoked multiple times for a given message. + + + + + + the request that was queued + + + + + + Emitted just before a request is sent. See +#SoupSession::request_queued for a detailed description of +the message lifecycle within a session. + Use #SoupMessage::starting instead. + + + + + + the request being sent + + + + the socket the request is being sent on + + + + + + Emitted when a request is removed from @session's queue, +indicating that @session is done with it. See +#SoupSession::request_queued for a detailed description of the +message lifecycle within a session. + + + + + + the request that was unqueued + + + + + + Emitted when an SSL tunnel is being created on a proxy +connection. This is an internal signal intended only to be +used for debugging purposes, and may go away in the future. + + + + + + the connection + + + + + + + + + Creates an asynchronous #SoupSession with the default options. + #SoupSessionAsync is deprecated; use a plain +#SoupSession, created with soup_session_new(). See the <link +linkend="libsoup-session-porting">porting guide</link>. + + + the new session. + + + + + Creates an asynchronous #SoupSession with the specified options. + #SoupSessionAsync is deprecated; use a plain +#SoupSession, created with soup_session_new_with_options(). See the +<link linkend="libsoup-session-porting">porting guide</link>. + + + the new session. + + + + + name of first property to set + + + + value of @optname1, followed by additional property/value pairs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Prototype for the callback passed to soup_session_queue_message(), +qv. + + + + + + + the session + + + + the message that has finished + + + + the data passed to soup_session_queue_message + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #SoupSession + + + + the message to queue + + + + a #SoupSessionCallback which will +be called after the message completes or when an unrecoverable error occurs. + + + + a pointer passed to @callback. + + + + + + + + + + + + + + a #SoupSession + + + + the message to requeue + + + + + + + + + + the HTTP status code of the response + + + + + a #SoupSession + + + + the message to send + + + + + + + + + + + + + + a #SoupSession + + + + the message to cancel + + + + status code to set on @msg (generally +%SOUP_STATUS_CANCELLED) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Prototype for the progress callback passed to soup_session_connect_async(). + + + + + + + the #SoupSession + + + + a #GSocketClientEvent + + + + the current state of the network connection + + + + the data passed to soup_session_connect_async(). + + + + + + An object that implement some sort of optional feature for +#SoupSession. + + + Adds a "sub-feature" of type @type to the base feature @feature. +This is used for features that can be extended with multiple +different types. Eg, the authentication manager can be extended +with subtypes of #SoupAuth. + + + %TRUE if @feature accepted @type as a subfeature. + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tests if @feature has a "sub-feature" of type @type. See +soup_session_feature_add_feature(). + + + %TRUE if @feature has a subfeature of type @type + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + Removes the "sub-feature" of type @type from the base feature +@feature. See soup_session_feature_add_feature(). + + + %TRUE if @type was removed from @feature + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Adds a "sub-feature" of type @type to the base feature @feature. +This is used for features that can be extended with multiple +different types. Eg, the authentication manager can be extended +with subtypes of #SoupAuth. + + + %TRUE if @feature accepted @type as a subfeature. + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Tests if @feature has a "sub-feature" of type @type. See +soup_session_feature_add_feature(). + + + %TRUE if @feature has a subfeature of type @type + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + Removes the "sub-feature" of type @type from the base feature +@feature. See soup_session_feature_add_feature(). + + + %TRUE if @type was removed from @feature + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + + The interface implemented by #SoupSessionFeature<!-- -->s. + + + The parent interface. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %TRUE if @feature accepted @type as a subfeature. + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + + + + + %TRUE if @type was removed from @feature + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + + + + + %TRUE if @feature has a subfeature of type @type + + + + + the "base" feature + + + + the #GType of a "sub-feature" + + + + + + + + + + Creates an synchronous #SoupSession with the default options. + #SoupSessionSync is deprecated; use a plain +#SoupSession, created with soup_session_new(). See the <link +linkend="libsoup-session-porting">porting guide</link>. + + + the new session. + + + + + Creates an synchronous #SoupSession with the specified options. + #SoupSessionSync is deprecated; use a plain +#SoupSession, created with soup_session_new_with_options(). See the +<link linkend="libsoup-session-porting">porting guide</link>. + + + the new session. + + + + + name of first property to set + + + + value of @optname1, followed by additional property/value pairs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new (disconnected) socket + + + the new socket + + + + + name of first property to set (or %NULL) + + + + value of @optname1, followed by additional property/value pairs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Begins asynchronously connecting to @sock's remote address. The +socket will call @callback when it succeeds or fails (but not +before returning from this function). + +If @cancellable is non-%NULL, it can be used to cancel the +connection. @callback will still be invoked in this case, with a +status of %SOUP_STATUS_CANCELLED. + + + + + + + a client #SoupSocket (which must not already be connected) + + + + a #GCancellable, or %NULL + + + + callback to call after connecting + + + + data to pass to @callback + + + + + + Attempt to synchronously connect @sock to its remote address. + +If @cancellable is non-%NULL, it can be used to cancel the +connection, in which case soup_socket_connect_sync() will return +%SOUP_STATUS_CANCELLED. + + + a success or failure code. + + + + + a client #SoupSocket (which must not already be connected) + + + + a #GCancellable, or %NULL + + + + + + Disconnects @sock. Any further read or write attempts on it will +fail. + + + + + + + a #SoupSocket + + + + + + Gets @sock's underlying file descriptor. + +Note that fiddling with the file descriptor may break the +#SoupSocket. + + + @sock's file descriptor. + + + + + a #SoupSocket + + + + + + Returns the #SoupAddress corresponding to the local end of @sock. + +Calling this method on an unconnected socket is considered to be +an error, and produces undefined results. + + + the #SoupAddress + + + + + a #SoupSocket + + + + + + Returns the #SoupAddress corresponding to the remote end of @sock. + +Calling this method on an unconnected socket is considered to be +an error, and produces undefined results. + + + the #SoupAddress + + + + + a #SoupSocket + + + + + + Tests if @sock is connected to another host + + + %TRUE or %FALSE. + + + + + a #SoupSocket + + + + + + Tests if @sock is doing (or has attempted to do) SSL. + + + %TRUE if @sock has SSL credentials set + + + + + a #SoupSocket + + + + + + Makes @sock start listening on its local address. When connections +come in, @sock will emit #SoupSocket::new_connection. + + + whether or not @sock is now listening. + + + + + a server #SoupSocket (which must not already be connected or +listening) + + + + + + Attempts to read up to @len bytes from @sock into @buffer. If some +data is successfully read, soup_socket_read() will return +%SOUP_SOCKET_OK, and *@nread will contain the number of bytes +actually read (which may be less than @len). + +If @sock is non-blocking, and no data is available, the return +value will be %SOUP_SOCKET_WOULD_BLOCK. In this case, the caller +can connect to the #SoupSocket::readable signal to know when there +is more data to read. (NB: You MUST read all available data off the +socket first. #SoupSocket::readable is only emitted after +soup_socket_read() returns %SOUP_SOCKET_WOULD_BLOCK, and it is only +emitted once. See the documentation for #SoupSocket:non-blocking.) + + + a #SoupSocketIOStatus, as described above (or +%SOUP_SOCKET_EOF if the socket is no longer connected, or +%SOUP_SOCKET_ERROR on any other error, in which case @error will +also be set). + + + + + the socket + + + + buffer to read + into + + + + + + size of @buffer in bytes + + + + on return, the number of bytes read into @buffer + + + + a #GCancellable, or %NULL + + + + + + Like soup_socket_read(), but reads no further than the first +occurrence of @boundary. (If the boundary is found, it will be +included in the returned data, and *@got_boundary will be set to +%TRUE.) Any data after the boundary will returned in future reads. + +soup_socket_read_until() will almost always return fewer than @len +bytes: if the boundary is found, then it will only return the bytes +up until the end of the boundary, and if the boundary is not found, +then it will leave the last <literal>(boundary_len - 1)</literal> +bytes in its internal buffer, in case they form the start of the +boundary string. Thus, @len normally needs to be at least 1 byte +longer than @boundary_len if you want to make any progress at all. + + + as for soup_socket_read() + + + + + the socket + + + + buffer to read + into + + + + + + size of @buffer in bytes + + + + boundary to read until + + + + length of @boundary in bytes + + + + on return, the number of bytes read into @buffer + + + + on return, whether or not the data in @buffer +ends with the boundary string + + + + a #GCancellable, or %NULL + + + + + + Starts using SSL on @socket, expecting to find a host named +@ssl_host. + + + success or failure + + + + + the socket + + + + hostname of the SSL server + + + + a #GCancellable + + + + + + Starts using SSL on @socket. + + + success or failure + + + + + the socket + + + + a #GCancellable + + + + + + Attempts to write @len bytes from @buffer to @sock. If some data is +successfully written, the return status will be %SOUP_SOCKET_OK, +and *@nwrote will contain the number of bytes actually written +(which may be less than @len). + +If @sock is non-blocking, and no data could be written right away, +the return value will be %SOUP_SOCKET_WOULD_BLOCK. In this case, +the caller can connect to the #SoupSocket::writable signal to know +when more data can be written. (NB: #SoupSocket::writable is only +emitted after soup_socket_write() returns %SOUP_SOCKET_WOULD_BLOCK, +and it is only emitted once. See the documentation for +#SoupSocket:non-blocking.) + + + a #SoupSocketIOStatus, as described above (or +%SOUP_SOCKET_EOF or %SOUP_SOCKET_ERROR. @error will be set if the +return value is %SOUP_SOCKET_ERROR.) + + + + + the socket + + + + data to write + + + + + + size of @buffer, in bytes + + + + on return, number of bytes written + + + + a #GCancellable, or %NULL + + + + + + + + + + + + + + + + + + + + + Whether or not the socket is a server socket. + +Note that for "ordinary" #SoupSockets this will be set for +both listening sockets and the sockets emitted by +#SoupSocket::new-connection, but for sockets created by +setting #SoupSocket:fd, it will only be set for listening +sockets. + + + + + + + Whether or not the socket uses non-blocking I/O. + +#SoupSocket's I/O methods are designed around the idea of +using a single codepath for both synchronous and +asynchronous I/O. If you want to read off a #SoupSocket, +the "correct" way to do it is to call soup_socket_read() or +soup_socket_read_until() repeatedly until you have read +everything you want. If it returns %SOUP_SOCKET_WOULD_BLOCK +at any point, stop reading and wait for it to emit the +#SoupSocket::readable signal. Then go back to the +reading-as-much-as-you-can loop. Likewise, for writing to a +#SoupSocket, you should call soup_socket_write() either +until you have written everything, or it returns +%SOUP_SOCKET_WOULD_BLOCK (in which case you wait for +#SoupSocket::writable and then go back into the loop). + +Code written this way will work correctly with both +blocking and non-blocking sockets; blocking sockets will +simply never return %SOUP_SOCKET_WOULD_BLOCK, and so the +code that handles that case just won't get used for them. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use g_main_context_get_thread_default(). + + + + + + + Emitted when the socket is disconnected, for whatever +reason. + + + + + + Emitted when a network-related event occurs. See +#GSocketClient::event for more details. + + + + + + the event that occurred + + + + the current connection state + + + + + + Emitted when a listening socket (set up with +soup_socket_listen()) receives a new connection. + +You must ref the @new if you want to keep it; otherwise it +will be destroyed after the signal is emitted. + + + + + + the new socket + + + + + + Emitted when an async socket is readable. See +soup_socket_read(), soup_socket_read_until() and +#SoupSocket:non-blocking. + + + + + + Emitted when an async socket is writable. See +soup_socket_write() and #SoupSocket:non-blocking. + + + + + + + The callback function passed to soup_socket_connect_async(). + + + + + + + the #SoupSocket + + + + an HTTP status code indicating success or failure + + + + the data passed to soup_socket_connect_async() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Return value from the #SoupSocket IO methods. + + Success + + + Cannot read/write any more at this time + + + End of file + + + Other error + + + + 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. + +Prior to 2.44 this type was called +<literal>SoupKnownStatusCode</literal>, but the individual values +have always had the names they have now. + + No status available. (Eg, the message has not +been sent yet) + + + Message was cancelled locally + + + Unable to resolve destination host name + + + Unable to resolve proxy host name + + + Unable to connect to remote host + + + Unable to connect to proxy + + + SSL/TLS negotiation failed + + + A network error occurred, or the other end +closed the connection unexpectedly + + + Malformed data (usually a programmer error) + + + Used internally + + + There were too many redirections + + + Used internally + + + 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) + + + 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) + + + 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. This is used +by soup_message_set_status() to get the correct text to go with a +given status code. + +<emphasis>There is no reason for you to ever use this +function.</emphasis> If you wanted the textual description for the +#SoupMessage:status_code of a given #SoupMessage, you should just +look at the message's #SoupMessage: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 + + + + + + Turns %SOUP_STATUS_CANT_RESOLVE into +%SOUP_STATUS_CANT_RESOLVE_PROXY and %SOUP_STATUS_CANT_CONNECT into +%SOUP_STATUS_CANT_CONNECT_PROXY. Other status codes are passed +through unchanged. + + + the "proxified" equivalent of @status_code. + + + + + a 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 + soup_tld_get_base_domain() on <literal>"co.uk"</literal>. + + + The passed-in hostname has + no recognized public suffix. + + + + + + + + + + + A #SoupURI represents a (parsed) URI. #SoupURI supports RFC 3986 +(URI Generic Syntax), and can parse any valid URI. However, libsoup +only uses "http" and "https" URIs internally; You can use +SOUP_URI_VALID_FOR_HTTP() to test if a #SoupURI is a valid HTTP +URI. + +@scheme will always be set in any URI. It is an interned string and +is always all lowercase. (If you parse a URI with a non-lowercase +scheme, it will be converted to lowercase.) The macros +%SOUP_URI_SCHEME_HTTP and %SOUP_URI_SCHEME_HTTPS provide the +interned values for "http" and "https" and can be compared against +URI @scheme values. + +@user and @password are parsed as defined in the older URI specs +(ie, separated by a colon; RFC 3986 only talks about a single +"userinfo" field). Note that @password is not included in the +output of soup_uri_to_string(). libsoup does not normally use these +fields; authentication is handled via #SoupSession signals. + +@host contains the hostname, and @port the port specified in the +URI. If the URI doesn't contain a hostname, @host will be %NULL, +and if it doesn't specify a port, @port may be 0. However, for +"http" and "https" URIs, @host is guaranteed to be non-%NULL +(trying to parse an http URI with no @host will return %NULL), and +@port will always be non-0 (because libsoup knows the default value +to use when it is not specified in the URI). + +@path is always non-%NULL. For http/https URIs, @path will never be +an empty string either; if the input URI has no path, the parsed +#SoupURI will have a @path of "/". + +@query and @fragment are optional for all URI types. +soup_form_decode() may be useful for parsing @query. + +Note that @path, @query, and @fragment may contain +%<!-- -->-encoded characters. soup_uri_new() calls +soup_uri_normalize() on them, but not soup_uri_decode(). This is +necessary to ensure that soup_uri_to_string() will generate a URI +that has exactly the same meaning as the original. (In theory, +#SoupURI should leave @user, @password, and @host partially-encoded +as well, but this would be more annoying than useful.) + + + the URI scheme (eg, "http") + + + + a username, or %NULL + + + + a password, or %NULL + + + + the hostname or IP address, or %NULL + + + + the port number on @host + + + + the path on @host + + + + a query for @path, or %NULL + + + + a fragment identifier within @path, or %NULL + + + + Parses an absolute URI. + +You can also pass %NULL for @uri_string if you want to get back an +"empty" #SoupURI that you can fill in by hand. (You will need to +call at least soup_uri_set_scheme() and soup_uri_set_path(), since +those fields are required.) + + + a #SoupURI, or %NULL if the given string + was found to be invalid. + + + + + a URI + + + + + + Parses @uri_string relative to @base. + + + a parsed #SoupURI. + + + + + a base URI + + + + the URI + + + + + + Copies @uri + + + a copy of @uri, which must be freed with soup_uri_free() + + + + + a #SoupURI + + + + + + Makes a copy of @uri, considering only the protocol, host, and port + + + the new #SoupURI + + + + + a #SoupURI + + + + + + Tests whether or not @uri1 and @uri2 are equal in all parts + + + %TRUE or %FALSE + + + + + a #SoupURI + + + + another #SoupURI + + + + + + Frees @uri. + + + + + + + a #SoupURI + + + + + + Gets @uri's fragment. + + + @uri's fragment. + + + + + a #SoupURI + + + + + + Gets @uri's host. + + + @uri's host. + + + + + a #SoupURI + + + + + + Gets @uri's password. + + + @uri's password. + + + + + a #SoupURI + + + + + + Gets @uri's path. + + + @uri's path. + + + + + a #SoupURI + + + + + + Gets @uri's port. + + + @uri's port. + + + + + a #SoupURI + + + + + + Gets @uri's query. + + + @uri's query. + + + + + a #SoupURI + + + + + + Gets @uri's scheme. + + + @uri's scheme. + + + + + a #SoupURI + + + + + + Gets @uri's user. + + + @uri's user. + + + + + a #SoupURI + + + + + + Compares @v1 and @v2, considering only the scheme, host, and port. + + + whether or not the URIs are equal in scheme, host, +and port. + + + + + a #SoupURI with a non-%NULL @host member + + + + a #SoupURI with a non-%NULL @host member + + + + + + Hashes @key, considering only the scheme, host, and port. + + + a hash + + + + + a #SoupURI with a non-%NULL @host member + + + + + + Sets @uri's fragment to @fragment. + + + + + + + a #SoupURI + + + + the fragment + + + + + + Sets @uri's host to @host. + +If @host is an IPv6 IP address, it should not include the brackets +required by the URI syntax; they will be added automatically when +converting @uri to a string. + +http and https URIs should not have a %NULL @host. + + + + + + + a #SoupURI + + + + the hostname or IP address, or %NULL + + + + + + Sets @uri's password to @password. + + + + + + + a #SoupURI + + + + the password, or %NULL + + + + + + Sets @uri's path to @path. + + + + + + + a #SoupURI + + + + the non-%NULL path + + + + + + Sets @uri's port to @port. If @port is 0, @uri will not have an +explicitly-specified port. + + + + + + + a #SoupURI + + + + the port, or 0 + + + + + + Sets @uri's query to @query. + + + + + + + a #SoupURI + + + + the query + + + + + + Sets @uri's query to the result of encoding the given form fields +and values according to the * HTML form rules. See +soup_form_encode() for more information. + + + + + + + a #SoupURI + + + + name of the first form field to encode into query + + + + value of @first_field, followed by additional field names +and values, terminated by %NULL. + + + + + + Sets @uri's query to the result of encoding @form according to the +HTML form rules. See soup_form_encode_hash() for more information. + + + + + + + a #SoupURI + + + + a #GHashTable containing HTML form +information + + + + + + + + + Sets @uri's scheme to @scheme. This will also set @uri's port to +the default port for @scheme, if known. + + + + + + + a #SoupURI + + + + the URI scheme + + + + + + Sets @uri's user to @user. + + + + + + + a #SoupURI + + + + the username, or %NULL + + + + + + Returns a string representing @uri. + +If @just_path_and_query is %TRUE, this concatenates the path and query +together. That is, it constructs the string that would be needed in +the Request-Line of an HTTP request for @uri. + +Note that the output will never contain a password, even if @uri +does. + + + a string representing @uri, which the caller must free. + + + + + a #SoupURI + + + + if %TRUE, output just the path and query portions + + + + + + Tests if @uri uses the default port for its scheme. (Eg, 80 for +http.) (This only works for http, https and ftp; libsoup does not know +the default ports of other protocols.) + + + %TRUE or %FALSE + + + + + a #SoupURI + + + + + + Fully %<!-- -->-decodes @part. + +In the past, this would return %NULL if @part contained invalid +percent-encoding, but now it just ignores the problem (as +soup_uri_new() already did). + + + the decoded URI part. + + + + + a URI part + + + + + + This %<!-- -->-encodes the given URI part and returns the escaped +version in allocated memory, which the caller must free when it is +done. + + + the encoded URI part + + + + + a URI part + + + + additional reserved characters to +escape (or %NULL) + + + + + + %<!-- -->-decodes any "unreserved" characters (or characters in +@unescape_extra) in @part, and %<!-- -->-encodes any non-ASCII +characters, spaces, and non-printing characters in @part. + +"Unreserved" characters are those that are not allowed to be used +for punctuation according to the URI spec. For example, letters are +unreserved, so soup_uri_normalize() will turn +<literal>http://example.com/foo/b%<!-- -->61r</literal> into +<literal>http://example.com/foo/bar</literal>, which is guaranteed +to mean the same thing. However, "/" is "reserved", so +<literal>http://example.com/foo%<!-- -->2Fbar</literal> would not +be changed, because it might mean something different to the +server. + +In the past, this would return %NULL if @part contained invalid +percent-encoding, but now it just ignores the problem (as +soup_uri_new() already did). + + + the normalized URI part + + + + + a URI part + + + + reserved characters to unescape (or %NULL) + + + + + + + Tests whether @uri is a valid #SoupURI; that is, that it is non-%NULL +and its @scheme and @path members are also non-%NULL. + +This macro does not check whether http and https URIs have a non-%NULL +@host member. + + + + a #SoupURI + + + + + Tests if @uri is a valid #SoupURI for HTTP communication; that is, if +it can be used to construct a #SoupMessage. + + + + a #SoupURI + + + + + Extracts a value of type @type from @val into @args. The return +value will point to the same data as @val rather than being a copy +of it. + Use #GVariant API instead. + + + + a #GValue + + + a #GType + + + #va_list pointing to a value of type pointer-to-@type + + + + + Copies an argument of type @type from @args into @val. @val will +point directly to the value in @args rather than copying it, so you +must g_value_copy() it if you want it to remain valid. + Use #GVariant API instead. + + + + a #GValue + + + a #GType + + + #va_list pointing to a value of type @type + + + + + 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 +soup_websocket_connection_close() or received from +soup_websocket_connection_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. + + + + A class representing a WebSocket connection. + + + Creates a #SoupWebsocketConnection on @stream. 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 + + + + + + Creates a #SoupWebsocketConnection 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 #SoupWebsocketConnection::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 +#SoupWebsocketCloseCode 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 maximum payload size allowed for incoming packets. + + + the maximum payload size. + + + + + the WebSocket + + + + + + Get the origin of the WebSocket. + + + the origin, or %NULL + + + + + the WebSocket + + + + + + Get the protocol chosen via negotiation with the peer. + + + the chosen protocol, or %NULL + + + + + 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 +soup_websocket_connection_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 + + + + + + Sets the maximum payload size allowed for incoming packets. It +does not limit the outgoing packet size. + + + + + + + the WebSocket + + + + the maximum payload size + + + + + + The type of connection (client/server). + + + + List of #SoupWebsocketExtension 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. + + + + The maximum payload size for incoming packets the protocol expects +or 0 to not limit it. + + + + 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, either +due to an orderly close from the peer, one initiated via +soup_websocket_connection_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 #SoupWebsocketConnection::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 +NUL-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 +NUL-terminated, but the NUL byte will not be included in +the length count. + + + + + + the application data (if any) + + + + + + + The abstract base class for #SoupWebsocketConnection + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The type of a #SoupWebsocketConnection. + + unknown/invalid connection + + + a client-side connection + + + a server-side connection + + + + The type of data contained in a #SoupWebsocketConnection::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. + + + + + + + + + + + + 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, or %NULL + + + + + + + + + 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 g_bytes_unref() is called on the given +@payload and a new #GBytes 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 g_bytes_unref() is called on the given +@payload and a new #GBytes 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, or %NULL + + + + + + + + + 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 g_bytes_unref() is called on the given +@payload and a new #GBytes 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 g_bytes_unref() is called on the given +@payload and a new #GBytes 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 SoupWebsocketExtension. + + + the parent class + + + + + + + + + + %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, or %NULL + + + + + + + + + + + + + a new allocated string with the parameters + + + + + a #SoupWebsocketExtension + + + + + + + + + + a new allocated string with the parameters + + + + + a #SoupWebsocketExtension + + + + + + + + + + the message payload data, or %NULL in case of error + + + + + a #SoupWebsocketExtension + + + + the message header + + + + the payload data + + + + + + + + + + the message payload data, or %NULL in case of error + + + + + a #SoupWebsocketExtension + + + + the message header + + + + the payload data + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + + + + + + + + + + + + + Pre-defined XML-RPC fault codes from <ulink +url="http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php">http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php</ulink>. +These are an extension, not part of the XML-RPC spec; you can't +assume servers will use them. + + request was not + well-formed + + + request was in + an unsupported encoding + + + request contained an invalid character + + + request was not + valid XML-RPC + + + method + not found + + + invalid + parameters + + + internal + error + + + start of reserved range for + application error codes + + + start of reserved range for + system error codes + + + start of reserved range for + transport error codes + + + + + + + + + + Opaque structure containing XML-RPC methodCall parameter values. +Can be parsed using soup_xmlrpc_params_parse() and freed with +soup_xmlrpc_params_free(). + + + Free a #SoupXMLRPCParams returned by soup_xmlrpc_parse_request(). + + + + + + + a SoupXMLRPCParams + + + + + + Parse method parameters returned by soup_xmlrpc_parse_request(). + +Deserialization details: + - If @signature is provided, &lt;int&gt; and &lt;i4&gt; can be deserialized + to byte, int16, uint16, int32, uint32, int64 or uint64. Otherwise + it will be deserialized to int32. If the value is out of range + for the target type it will return an error. + - &lt;struct&gt; will be deserialized to "a{sv}". @signature could define + another value type (e.g. "a{ss}"). + - &lt;array&gt; will be deserialized to "av". @signature could define + another element type (e.g. "as") or could be a tuple (e.g. "(ss)"). + - &lt;base64&gt; will be deserialized to "ay". + - &lt;string&gt; will be deserialized to "s". + - &lt;dateTime.iso8601&gt; will be deserialized to an unspecified variant + type. If @signature is provided it must have the generic "v" type, which + means there is no guarantee that it's actually a datetime that has been + received. soup_xmlrpc_variant_get_datetime() must be used to parse and + type check this special variant. + - @signature must not have maybes, otherwise an error is returned. + - Dictionaries must have string keys, otherwise an error is returned. + + + a new (non-floating) #GVariant, or %NULL + + + + + A #SoupXMLRPCParams + + + + A valid #GVariant type string, or %NULL + + + + + + + Adds @function to be executed from inside @async_context with the +default priority. Use this when you want to complete an action in +@async_context's main loop, as soon as possible. + + + a #GSource, which can be removed from @async_context +with g_source_destroy(). + + + + + the #GMainContext to dispatch the I/O +watch in, or %NULL for the default context + + + + the callback to invoke + + + + user data to pass to @function + + + + + + Adds an idle event as with g_idle_add(), but using the given +@async_context. + +If you want @function to run "right away", use +soup_add_completion(), since that sets a higher priority on the +#GSource than soup_add_idle() does. + + + a #GSource, which can be removed from @async_context +with g_source_destroy(). + + + + + the #GMainContext to dispatch the I/O +watch in, or %NULL for the default context + + + + the callback to invoke at idle time + + + + user data to pass to @function + + + + + + Adds an I/O watch as with g_io_add_watch(), but using the given +@async_context. + + + a #GSource, which can be removed from @async_context +with g_source_destroy(). + + + + + the #GMainContext to dispatch the I/O +watch in, or %NULL for the default context + + + + the #GIOChannel to watch + + + + the condition to watch for + + + + the callback to invoke when @condition occurs + + + + user data to pass to @function + + + + + + Adds a timeout as with g_timeout_add(), but using the given +@async_context. + + + a #GSource, which can be removed from @async_context +with g_source_destroy(). + + + + + the #GMainContext to dispatch the I/O +watch in, or %NULL for the default context + + + + the timeout interval, in milliseconds + + + + the callback to invoke at timeout time + + + + user data to pass to @function + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Like SOUP_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 #SoupCookie. (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 #SoupCookie, and you will need to fill in some +appropriate string for the domain if you want to actually make use +of the cookie. + + + 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, or %NULL + + + + + + Frees @cookies. + + + + + + + a #GSList of #SoupCookie + + + + + + + + Parses @msg's Cookie request header and returns a #GSList of +#SoupCookie<!-- -->s. As the "Cookie" header, unlike "Set-Cookie", +only contains cookie names and values, none of the other +#SoupCookie fields will be filled in. (Thus, you can't generally +pass a cookie returned from this method directly to +soup_cookies_to_response().) + + + a #GSList +of #SoupCookie<!-- -->s, which can be freed with +soup_cookies_free(). + + + + + + + a #SoupMessage containing a "Cookie" request header + + + + + + Parses @msg's Set-Cookie response headers and returns a #GSList 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 +soup_cookies_free(). + + + + + + + a #SoupMessage containing a "Set-Cookie" response header + + + + + + Serializes a #GSList of #SoupCookie into a string suitable for +setting as the value of the "Cookie" header. + + + the serialization of @cookies + + + + + a #GSList of #SoupCookie + + + + + + + + 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 #SoupCookie + + + + + + 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 #SoupCookie + + + + + + a #SoupMessage + + + + + + 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 g_hash_table_destroy(). + + + + + + + + data of type "application/x-www-form-urlencoded" + + + + + + Decodes the "multipart/form-data" request in @msg; 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 +soup_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 +soup_form_decode()) in the returned #GHashTable. + +You may pass %NULL for @filename, @content_type and/or @file if you do not +care about those fields. soup_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 g_free(), and the returned file data with soup_buffer_free(). + +If you have a form with more than one file upload control, you will +need to decode it manually, using soup_multipart_new_from_message() +and soup_multipart_get_part(). + + + +a hash table containing the name/value pairs (other than +@file_control_name) from @msg, which you can free with +g_hash_table_destroy(). On error, it will return %NULL. + + + + + + + + a #SoupMessage containing a "multipart/form-data" request body + + + + the name of the HTML file upload control, or %NULL + + + + return location for the name of the uploaded file, or %NULL + + + + return location for the MIME type of the uploaded file, or %NULL + + + + return location for the uploaded file data, or %NULL + + + + + + Encodes the given field names and values into a value of type +"application/x-www-form-urlencoded", 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 soup_form_encode_hash() or +soup_form_encode_datalist(). + + + 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", as defined in the HTML 4.01 +spec. Unlike soup_form_encode_hash(), this preserves the ordering +of the form elements, which may be required in some situations. + + + the encoded form + + + + + a datalist containing name/value pairs + + + + + + Encodes @form_data_set into a value of type +"application/x-www-form-urlencoded", 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 soup_form_encode_datalist(). + + + the encoded form + + + + + a hash table containing +name/value pairs (as strings) + + + + + + + + + See soup_form_encode(). This is mostly an internal method, used by +various other methods such as soup_uri_set_query_from_fields() and +soup_form_request_new(). + + + the encoded form + + + + + name of the first form field + + + + pointer to additional values, as in soup_form_encode() + + + + + + Creates a new %SoupMessage and sets it up to send the given data +to @uri via @method. (That is, if @method is "GET", it will encode +the form data into @uri's query field, and if @method is "POST", it +will encode it into the %SoupMessage's request_body.) + + + the new %SoupMessage + + + + + the HTTP method, either "GET" or "POST" + + + + the URI to send the form data to + + + + name of the first form field + + + + value of @first_field, followed by additional field names +and values, terminated by %NULL. + + + + + + Creates a new %SoupMessage and sets it up to send @form_data_set to +@uri via @method, as with soup_form_request_new(). + + + the new %SoupMessage + + + + + the HTTP method, either "GET" or "POST" + + + + the URI to send the form data to + + + + the data to send to @uri + + + + + + Creates a new %SoupMessage and sets it up to send @form_data_set to +@uri via @method, as with soup_form_request_new(). + + + the new %SoupMessage + + + + + the HTTP method, either "GET" or "POST" + + + + the URI to send the form data to + + + + the data to send to @uri + + + + + + + + + Creates a new %SoupMessage and sets it up to send @multipart to +@uri via POST. + +To send a <literal>"multipart/form-data"</literal> POST, first +create a #SoupMultipart, using %SOUP_FORM_MIME_TYPE_MULTIPART as +the MIME type. Then use soup_multipart_append_form_string() and +soup_multipart_append_form_file() to add the value of each form +control to the multipart. (These are just convenience methods, and +you can use soup_multipart_append_part() if you need greater +control over the part headers.) Finally, call +soup_form_request_new_from_multipart() to serialize the multipart +structure and create a #SoupMessage. + + + the new %SoupMessage + + + + + the URI to send the form data to + + + + a "multipart/form-data" #SoupMultipart + + + + + + 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 +soup_header_parse_list() + + + + a token + + + + + + Frees @list. + + + + + + + a #GSList returned from soup_header_parse_list() or +soup_header_parse_quality_list() + + + + + + + + Frees @param_list. + + + + + + + a #GHashTable returned from soup_header_parse_param_list() +or soup_header_parse_semi_param_list() + + + + + + + + + Appends something like <literal>@name=@value</literal> 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 <literal>@name="@value"</literal> 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 soup_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", where "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: +<literal>token [ "=" ( token | quoted-string ) ]</literal>. + +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 +soup_header_free_param_list(). + + + + + + + + a header value + + + + + + A strict version of soup_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 +soup_header_parse_param_list() instead. + + + +a #GHashTable of list elements, which can be freed with +soup_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: <literal>token [ "=" ( token | quoted-string ) ]</literal>. + +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 +soup_header_free_param_list(). + + + + + + + + a header value + + + + + + A strict version of soup_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 +soup_header_parse_semi_param_list() instead. + + + +a #GHashTable of list elements, which can be freed with +soup_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 +soup_headers_parse_request() or soup_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 + + + + + + + + + + + + + + + + Looks up the stock HTTP description of @status_code. This is used +by soup_message_set_status() to get the correct text to go with a +given status code. + +<emphasis>There is no reason for you to ever use this +function.</emphasis> If you wanted the textual description for the +#SoupMessage:status_code of a given #SoupMessage, you should just +look at the message's #SoupMessage: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 + + + + + + Turns %SOUP_STATUS_CANT_RESOLVE into +%SOUP_STATUS_CANT_RESOLVE_PROXY and %SOUP_STATUS_CANT_CONNECT into +%SOUP_STATUS_CANT_CONNECT_PROXY. Other status codes are passed +through unchanged. + + + the "proxified" equivalent of @status_code. + + + + + a status code + + + + + + Compares @v1 and @v2 in a case-insensitive manner + + + %TRUE if they are equal (modulo case) + + + + + an ASCII string + + + + another ASCII string + + + + + + Hashes @key in a case-insensitive manner. + + + the hash code. + + + + + ASCII string to hash + + + + + + 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 + + + + + + + + + + + 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 + + + + + + Fully %<!-- -->-decodes @part. + +In the past, this would return %NULL if @part contained invalid +percent-encoding, but now it just ignores the problem (as +soup_uri_new() already did). + + + the decoded URI part. + + + + + a URI part + + + + + + This %<!-- -->-encodes the given URI part and returns the escaped +version in allocated memory, which the caller must free when it is +done. + + + the encoded URI part + + + + + a URI part + + + + additional reserved characters to +escape (or %NULL) + + + + + + %<!-- -->-decodes any "unreserved" characters (or characters in +@unescape_extra) in @part, and %<!-- -->-encodes any non-ASCII +characters, spaces, and non-printing characters in @part. + +"Unreserved" characters are those that are not allowed to be used +for punctuation according to the URI spec. For example, letters are +unreserved, so soup_uri_normalize() will turn +<literal>http://example.com/foo/b%<!-- -->61r</literal> into +<literal>http://example.com/foo/bar</literal>, which is guaranteed +to mean the same thing. However, "/" is "reserved", so +<literal>http://example.com/foo%<!-- -->2Fbar</literal> would not +be changed, because it might mean something different to the +server. + +In the past, this would return %NULL if @part contained invalid +percent-encoding, but now it just ignores the problem (as +soup_uri_new() already did). + + + the normalized URI part + + + + + a URI part + + + + reserved characters to unescape (or %NULL) + + + + + + Appends the provided value of type @type to @array as with +g_value_array_append(). (The provided data is copied rather than +being inserted directly.) + Use #GVariant API instead. + + + + + + + a #GValueArray + + + + a #GType + + + + a value of type @type + + + + + + Appends the provided values into @array as with +g_value_array_append(). (The provided data is copied rather than +being inserted directly.) + Use #GVariant API instead. + + + + + + + a #GValueArray + + + + the type of the first value to add + + + + the first value to add, followed by other type/value +pairs, terminated by %G_TYPE_INVALID + + + + + + Creates a #GValueArray from the provided arguments, which must +consist of pairs of a #GType and a value of that type, terminated +by %G_TYPE_INVALID. (The array will contain copies of the provided +data rather than pointing to the passed-in data directly.) + Use #GVariant API instead. + + + a new #GValueArray, or %NULL if an error +occurred. + + + + + arguments to create a #GValueArray from + + + + + + Gets the @index_ element of @array and stores its value into the +provided location. + Use #GVariant API instead. + + + %TRUE if @array contained a value with index @index_ +and type @type, %FALSE if not. + + + + + a #GValueArray + + + + the index to look up + + + + a #GType + + + + a value of type pointer-to-@type + + + + + + Inserts the provided value of type @type into @array as with +g_value_array_insert(). (The provided data is copied rather than +being inserted directly.) + Use #GVariant API instead. + + + + + + + a #GValueArray + + + + the index to insert at + + + + a #GType + + + + a value of type @type + + + + + + Creates a new %GValueArray. (This is just a wrapper around +g_value_array_new(), for naming consistency purposes.) + Use #GVariant API instead. + + + a new %GValueArray + + + + + Creates a new %GValueArray and copies the provided values +into it. + Use #GVariant API instead. + + + a new %GValueArray + + + + + the type of the first value to add + + + + the first value to add, followed by other type/value +pairs, terminated by %G_TYPE_INVALID + + + + + + Extracts a #GValueArray into the provided arguments, which must +consist of pairs of a #GType and a value of pointer-to-that-type, +terminated by %G_TYPE_INVALID. The returned values will point to the +same memory as the values in the array. + Use #GVariant API instead. + + + success or failure + + + + + a #GValueArray + + + + arguments to extract @array into + + + + + + Inserts the provided value of type @type into @hash. (Unlike with +g_hash_table_insert(), both the key and the value are copied). + Use #GVariant API instead. + + + + + + + a value hash + + + + + + + the key + + + + a #GType + + + + a value of type @type + + + + + + Inserts the given data into @hash. As with +soup_value_hash_insert(), the keys and values are copied rather +than being inserted directly. + Use #GVariant API instead. + + + + + + + a value hash + + + + + + + the key for the first value + + + + the type of @first_key, followed by the value, followed +by additional key/type/value triplets, terminated by %NULL + + + + + + Inserts @value into @hash. (Unlike with g_hash_table_insert(), both +the key and the value are copied). + Use #GVariant API instead. + + + + + + + a value hash + + + + + + + the key + + + + a value + + + + + + Looks up @key in @hash and stores its value into the provided +location. + Use #GVariant API instead. + + + %TRUE if @hash contained a value with key @key and +type @type, %FALSE if not. + + + + + a value hash + + + + + + + the key to look up + + + + a #GType + + + + a value of type pointer-to-@type + + + + + + Looks up a number of keys in @hash and returns their values. + Use #GVariant API instead. + + + %TRUE if all of the keys were found, %FALSE +if any were missing; note that you will generally need to +initialize each destination variable to a reasonable default +value, since there is no way to tell which keys were found +and which were not. + + + + + a value hash + + + + + + + the first key to look up + + + + the type of @first_key, a pointer to that type, and +then additional key/type/pointer triplets, terminated +by %NULL. + + + + + + Creates a #GHashTable whose keys are strings and whose values +are #GValue. + Use #GVariant API instead. + + + a new +empty #GHashTable + + + + + + + + Creates a #GHashTable whose keys are strings and whose values +are #GValue, and initializes it with the provided data. As +with soup_value_hash_insert(), the keys and values are copied +rather than being inserted directly. + Use #GVariant API instead. + + + a new +#GHashTable, initialized with the given values + + + + + + + + the key for the first value + + + + the type of @first_key, followed by the value, followed +by additional key/type/value triplets, terminated by %NULL + + + + + + Adds the necessary headers to @msg to request a WebSocket +handshake. The message body and non-WebSocket-related headers are +not modified. + +Use soup_websocket_client_prepare_handshake_with_extensions() if you +want to include "Sec-WebSocket-Extensions" header in the request. + +This is a low-level function; if you use +soup_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 + + + + + + + + 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 +soup_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 the response contains the "Sec-WebSocket-Extensions" header, +the handshake will be considered invalid. You need to use +soup_websocket_client_verify_handshake_with_extensions() to handle +responses with extensions. + +This is a low-level function; if you use +soup_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 + + + + + + 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 +soup_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 #SoupWebsocketExtension objects + + + + + + + + + + + + + + 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. + +Requests containing "Sec-WebSocket-Extensions" header will be +accepted even if the header is not valid. To check a request +with extensions you need to use +soup_websocket_server_check_handshake_with_extensions() and provide +the list of supported extension types. + +Normally soup_websocket_server_process_handshake() will take care +of this for you, and if you use soup_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. + + + + + #SoupMessage containing the client side of a WebSocket handshake + + + + expected Origin header + + + + allowed WebSocket + protocols. + + + + + + + + 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 soup_websocket_server_process_handshake_with_extensioins() +will take care of this for you, and if you use +soup_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. + + + + + #SoupMessage 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. + +Requests containing "Sec-WebSocket-Extensions" header will be +accepted even if the header is not valid. To process a request +with extensions you need to use +soup_websocket_server_process_handshake_with_extensions() and provide +the list of supported extension types. + +This is a low-level function; if you use +soup_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. + + + + + #SoupMessage containing the client side of a WebSocket handshake + + + + expected Origin header + + + + allowed WebSocket + protocols. + + + + + + + + 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 +soup_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. + + + + + #SoupMessage containing the client side of a WebSocket handshake + + + + expected Origin header + + + + allowed WebSocket + protocols. + + + + + + list + of supported extension types + + + + + + a + #GList of #SoupWebsocketExtension objects + + + + + + + + This creates an XML-RPC fault response and returns it as a string. +(To create a successful response, use +soup_xmlrpc_build_method_response().) + + + the text of the fault + + + + + the fault code + + + + a printf()-style format string + + + + the parameters to @fault_format + + + + + + This creates an XML-RPC methodCall and returns it as a string. +This is the low-level method that soup_xmlrpc_request_new() is +built on. + +@params is an array of #GValue representing the parameters to +@method. (It is *not* a #GValueArray, although if you have a +#GValueArray, you can just pass its <literal>values</literal>f and +<literal>n_values</literal> fields.) + +The correspondence between glib types and XML-RPC types is: + + int: #int (%G_TYPE_INT) + boolean: #gboolean (%G_TYPE_BOOLEAN) + string: #char* (%G_TYPE_STRING) + double: #double (%G_TYPE_DOUBLE) + datetime.iso8601: #SoupDate (%SOUP_TYPE_DATE) + base64: #GByteArray (%SOUP_TYPE_BYTE_ARRAY) + struct: #GHashTable (%G_TYPE_HASH_TABLE) + array: #GValueArray (%G_TYPE_VALUE_ARRAY) + +For structs, use a #GHashTable that maps strings to #GValue; +soup_value_hash_new() and related methods can help with this. + Use soup_xmlrpc_build_request() instead. + + + the text of the methodCall, or %NULL on +error + + + + + the name of the XML-RPC method + + + + arguments to @method + + + + + + length of @params + + + + + + This creates a (successful) XML-RPC methodResponse and returns it +as a string. To create a fault response, use +soup_xmlrpc_build_fault(). + +The glib type to XML-RPC type mapping is as with +soup_xmlrpc_build_method_call(), qv. + Use soup_xmlrpc_build_response() instead. + + + the text of the methodResponse, or %NULL +on error + + + + + the return value + + + + + + This creates an XML-RPC methodCall and returns it as a string. +This is the low-level method that soup_xmlrpc_message_new() is +built on. + +@params is a #GVariant tuple representing the method parameters. + +Serialization details: + - "a{s*}" and "{s*}" are serialized as &lt;struct&gt; + - "ay" is serialized as &lt;base64&gt; + - Other arrays and tuples are serialized as &lt;array&gt; + - booleans are serialized as &lt;boolean&gt; + - byte, int16, uint16 and int32 are serialized as &lt;int&gt; + - uint32 and int64 are serialized as the nonstandard &lt;i8&gt; type + - doubles are serialized as &lt;double&gt; + - Strings are serialized as &lt;string&gt; + - Variants (i.e. "v" type) are unwrapped and their child is serialized. + - #GVariants created by soup_xmlrpc_variant_new_datetime() are serialized as + &lt;dateTime.iso8601&gt; + - Other types are not supported and will return %NULL and set @error. + This notably includes: object-paths, signatures, uint64, handles, maybes + and dictionaries with non-string keys. + +If @params is floating, it is consumed. + + + the text of the methodCall, or %NULL on error. + + + + + the name of the XML-RPC method + + + + a #GVariant tuple + + + + + + This creates a (successful) XML-RPC methodResponse and returns it +as a string. To create a fault response, use soup_xmlrpc_build_fault(). This +is the low-level method that soup_xmlrpc_message_set_response() is built on. + +See soup_xmlrpc_build_request() for serialization details, but note +that since a method can only have a single return value, @value +should not be a tuple here (unless the return value is an array). + +If @value is floating, it is consumed. + + + the text of the methodResponse, or %NULL on error. + + + + + the return value + + + + + + + + + + + Parses @method_call to get the name and parameters, and puts +the parameters into variables of the appropriate types. + +The parameters are handled similarly to +@soup_xmlrpc_build_method_call, with pairs of types and values, +terminated by %G_TYPE_INVALID, except that values are pointers to +variables of the indicated type, rather than values of the type. + +See also soup_xmlrpc_parse_method_call(), which can be used if +you don't know the types of the parameters. + Use soup_xmlrpc_parse_request_full() instead. + + + success or failure. + + + + + the XML-RPC methodCall string + + + + the length of @method_call, or -1 if it is NUL-terminated + + + + on return, the methodName from @method_call + + + + return types and locations for parameters + + + + + + Parses @method_response and extracts the return value into +a variable of the correct type. + +If @method_response is a fault, the return value will be unset, +and @error will be set to an error of type %SOUP_XMLRPC_FAULT, with +the error #code containing the fault code, and the error #message +containing the fault string. (If @method_response cannot be parsed +at all, soup_xmlrpc_extract_method_response() will return %FALSE, +but @error will be unset.) + Use soup_xmlrpc_parse_response() instead. + + + %TRUE if a return value was parsed, %FALSE if the +response was of the wrong type, or contained a fault. + + + + + the XML-RPC methodResponse string + + + + the length of @method_response, or -1 if it is NUL-terminated + + + + error return value + + + + the expected type of the return value + + + + location for return value + + + + + + + + + + + + Creates an XML-RPC methodCall and returns a #SoupMessage, ready +to send, for that method call. + +See soup_xmlrpc_build_request() for serialization details. + +If @params is floating, it is consumed. + + + a #SoupMessage encoding the + indicated XML-RPC request, or %NULL on error. + + + + + URI of the XML-RPC service + + + + the name of the XML-RPC method to invoke at @uri + + + + a #GVariant tuple + + + + + + Sets the status code and response body of @msg to indicate an +unsuccessful XML-RPC call, with the error described by @fault_code +and @fault_format. + + + + + + + an XML-RPC request + + + + the fault code + + + + a printf()-style format string + + + + the parameters to @fault_format + + + + + + Sets the status code and response body of @msg to indicate a +successful XML-RPC call, with a return value given by @value. To set a +fault response, use soup_xmlrpc_message_set_fault(). + +See soup_xmlrpc_build_request() for serialization details. + +If @value is floating, it is consumed. + + + %TRUE on success, %FALSE otherwise. + + + + + an XML-RPC request + + + + a #GVariant + + + + + + Parses @method_call to get the name and parameters, and returns the +parameter values in a #GValueArray; see also +soup_xmlrpc_extract_method_call(), which is more convenient if you +know in advance what the types of the parameters will be. + Use soup_xmlrpc_parse_request_full() instead. + + + success or failure. + + + + + the XML-RPC methodCall string + + + + the length of @method_call, or -1 if it is NUL-terminated + + + + on return, the methodName from @method_call + + + + on return, the parameters from @method_call + + + + + + Parses @method_response and returns the return value in @value. If +@method_response is a fault, @value will be unchanged, and @error +will be set to an error of type %SOUP_XMLRPC_FAULT, with the error +#code containing the fault code, and the error #message containing +the fault string. (If @method_response cannot be parsed at all, +soup_xmlrpc_parse_method_response() will return %FALSE, but @error +will be unset.) + Use soup_xmlrpc_parse_response() instead. + + + %TRUE if a return value was parsed, %FALSE if the +response could not be parsed, or contained a fault. + + + + + the XML-RPC methodResponse string + + + + the length of @method_response, or -1 if it is NUL-terminated + + + + on return, the return value from @method_call + + + + + + Parses @method_call and return the method name. Method parameters can be +parsed later using soup_xmlrpc_params_parse(). + + + method's name, or %NULL on error. + + + + + the XML-RPC methodCall string + + + + the length of @method_call, or -1 if it is NUL-terminated + + + + on success, a new #SoupXMLRPCParams + + + + + + Parses @method_response and returns the return value. If +@method_response is a fault, %NULL is returned, and @error +will be set to an error in the %SOUP_XMLRPC_FAULT domain, with the error +code containing the fault code, and the error message containing +the fault string. If @method_response cannot be parsed, %NULL is returned, +and @error will be set to an error in the %SOUP_XMLRPC_ERROR domain. + +See soup_xmlrpc_params_parse() for deserialization details. + + + a new (non-floating) #GVariant, or %NULL + + + + + the XML-RPC methodResponse string + + + + the length of @method_response, or -1 if it is NUL-terminated + + + + A valid #GVariant type string, or %NULL + + + + + + Creates an XML-RPC methodCall and returns a #SoupMessage, ready +to send, for that method call. + +The parameters are passed as type/value pairs; ie, first a #GType, +and then a value of the appropriate type, finally terminated by +%G_TYPE_INVALID. + Use soup_xmlrpc_message_new() instead. + + + a #SoupMessage encoding the +indicated XML-RPC request. + + + + + URI of the XML-RPC service + + + + the name of the XML-RPC method to invoke at @uri + + + + parameters for @method + + + + + + Sets the status code and response body of @msg to indicate an +unsuccessful XML-RPC call, with the error described by @fault_code +and @fault_format. + Use soup_xmlrpc_message_set_fault() instead. + + + + + + + an XML-RPC request + + + + the fault code + + + + a printf()-style format string + + + + the parameters to @fault_format + + + + + + Sets the status code and response body of @msg to indicate a +successful XML-RPC call, with a return value given by @type and the +following varargs argument, of the type indicated by @type. + Use soup_xmlrpc_message_set_response() instead. + + + + + + + an XML-RPC request + + + + the type of the response value + + + + the response value + + + + + + Get the #SoupDate from special #GVariant created by +soup_xmlrpc_variant_new_datetime() or by parsing a &lt;dateTime.iso8601&gt; +node. See soup_xmlrpc_params_parse(). + +If @variant does not contain a datetime it will return an error but it is not +considered a programmer error because it generally means parameters received +are not in the expected type. + + + a new #SoupDate, or %NULL on error. + + + + + a #GVariant + + + + + + Construct a special #GVariant used to serialize a &lt;dateTime.iso8601&gt; +node. See soup_xmlrpc_build_request(). + +The actual type of the returned #GVariant is unspecified and "v" or "*" +should be used in variant format strings. For example: +<informalexample><programlisting> +args = g_variant_new ("(v)", soup_xmlrpc_variant_new_datetime (date)); +</programlisting></informalexample> + + + a floating #GVariant. + + + + + a #SoupDate + + + + + + diff --git a/gir-files/Vte-2.91.gir b/gir-files/Vte-2.91.gir new file mode 100644 index 0000000..9f6a34d --- /dev/null +++ b/gir-files/Vte-2.91.gir @@ -0,0 +1,4333 @@ + + + + + + + + + + + Macro to check the library version at compile time. +It returns %1 if the version of VTE is greater or +equal to the required one, and %0 otherwise. + + + + required major version + + + required minor version + + + required micro version + + + + + + + + + + + + + + + + + + + + + + + + + + + + + An enumerated type which can be used to indicate the cursor blink mode +for the terminal. + + Follow GTK+ settings for cursor blinking. + + + Cursor blinks. + + + Cursor does not blink. + + + + An enumerated type which can be used to indicate what should the terminal +draw at the cursor position. + + Draw a block cursor. This is the default. + + + Draw a vertical bar on the left side of character. +This is similar to the default cursor for other GTK+ widgets. + + + Draw a horizontal bar below the character. + + + + An enumerated type which can be used to indicate which string the terminal +should send to an application when the user presses the Delete or Backspace +keys. + + For backspace, attempt to determine the right value from the terminal's IO settings. For delete, use the control sequence. + + + Send an ASCII backspace character (0x08). + + + Send an ASCII delete character (0x7F). + + + Send the "@@7" control sequence. + + + Send terminal's "erase" setting. + + + + An enumeratio type that can be used to specify the format the selection +should be copied to the clipboard in. + + Export as plain text + + + Export as HTML formatted text + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The major version number of the VTE library +(e.g. in version 3.1.4 this is 3). + + + + + The micro version number of the VTE library +(e.g. in version 3.1.4 this is 4). + + + + + The minor version number of the VTE library +(e.g. in version 3.1.4 this is 1). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #VtePty for the PTY master @fd. + +No entry will be made in the lastlog, utmp or wtmp system files. + +Note that the newly created #VtePty will take ownership of @fd +and close it on finalize. + + + a new #VtePty for @fd, or %NULL on error with @error filled in + + + + + a file descriptor to the PTY + + + + a #GCancellable, or %NULL + + + + + + Allocates a new pseudo-terminal. + +You can later use fork() or the g_spawn_async() family of functions +to start a process on the PTY. + +If using fork(), you MUST call vte_pty_child_setup() in the child. + +If using g_spawn_async() and friends, you MUST either use +vte_pty_child_setup() directly as the child setup function, or call +vte_pty_child_setup() from your own child setup function supplied. + +When using vte_terminal_spawn_sync() with a custom child setup +function, vte_pty_child_setup() will be called before the supplied +function; you must not call it again. + +Also, you MUST pass the %G_SPAWN_DO_NOT_REAP_CHILD flag. + + + a new #VtePty, or %NULL on error with @error filled in + + + + + flags from #VtePtyFlags + + + + a #GCancellable, or %NULL + + + + + + FIXMEchpe + + + + + + + a #VtePty + + + + + + Since 0.42 this is a no-op. + + + + + + + a #VtePty + + + + + + + + the file descriptor of the PTY master in @pty. The + file descriptor belongs to @pty and must not be closed of have + its flags changed + + + + + a #VtePty + + + + + + Reads the pseudo terminal's window size. + +If getting the window size failed, @error will be set to a #GIOError. + + + %TRUE on success, %FALSE on failure with @error filled in + + + + + a #VtePty + + + + a location to store the number of rows, or %NULL + + + + a location to store the number of columns, or %NULL + + + + + + Attempts to resize the pseudo terminal's window size. If successful, the +OS kernel will send #SIGWINCH to the child process group. + +If setting the window size failed, @error will be set to a #GIOError. + + + %TRUE on success, %FALSE on failure with @error filled in + + + + + a #VtePty + + + + the desired number of rows + + + + the desired number of columns + + + + + + Tells the kernel whether the terminal is UTF-8 or not, in case it can make +use of the info. Linux 2.6.5 or so defines IUTF8 to make the line +discipline do multibyte backspace correctly. + + + %TRUE on success, %FALSE on failure with @error filled in + + + + + a #VtePty + + + + whether or not the pty is in UTF-8 mode + + + + + + Starts the specified command under the pseudo-terminal @pty. +The @argv and @envv lists should be %NULL-terminated. +The "TERM" environment variable is automatically set to a default value, +but can be overridden from @envv. +@pty_flags controls logging the session to the specified system log files. + +Note that %G_SPAWN_DO_NOT_REAP_CHILD will always be added to @spawn_flags. + +Note that all open file descriptors will be closed in the child. If you want +to keep some file descriptor open for use in the child process, you need to +use a child setup function that unsets the FD_CLOEXEC flag on that file +descriptor. + +See vte_pty_new(), g_spawn_async() and vte_terminal_watch_child() for more information. + + + + + + + a #VtePty + + + + the name of a directory the command should start + in, or %NULL to use the current working directory + + + + child's argument vector + + + + + + a list of environment + variables to be added to the environment before starting the process, or %NULL + + + + + + flags from #GSpawnFlags + + + + an extra child setup function to run in the child just before exec(), or %NULL + + + + user data for @child_setup, or %NULL + + + + a #GDestroyNotify for @child_setup_data, or %NULL + + + + a timeout value in ms, or -1 to wait indefinitely + + + + a #GCancellable, or %NULL + + + + + + + + + + + + + + %TRUE on success, or %FALSE on error with @error filled in + + + + + a #VtePty + + + + a #GAsyncResult + + + + a location to store the child PID, or %NULL + + + + + + The file descriptor of the PTY master. + + + + Flags. + + + + + + + + + Obsolete. Deprecated: 0.42 + + + failure when using PTY98 to allocate the PTY + + + Error domain for VTE PTY errors. Errors in this domain will be from the #VtePtyError +enumeration. See #GError for more information on error domains. + + the error domain for VTE PTY errors + + + + + + + Unused. Deprecated: 0.38 + + + Unused. Deprecated: 0.38 + + + Unused. Deprecated: 0.38 + + + Unused. Deprecated: 0.38 + + + Unused. Deprecated: 0.38 + + + Do not start a new session for the child in + vte_pty_child_setup(). See man:setsid(2) for more information. Since: 0.58 + + + Do not set the PTY as the controlling TTY for the child + in vte_pty_child_setup(). See man:tty_ioctl(4) for more information. Since: 0.58 + + + the default flags + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + An enum type for regex errors. In addition to the values listed above, +any PCRE2 error values may occur. + + The PCRE2 library was built without + Unicode support which is required for VTE + + + Regexes are not supported because VTE was + built without PCRE2 support + + + + + + + + + + + + + Specifies the type of a selection function used to check whether +a cell has to be selected or not. + + + %TRUE if cell has to be selected; %FALSE if otherwise. + + + + + terminal in which the cell is. + + + + column in which the cell is. + + + + row in which the cell is. + + + + user data. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new terminal widget. + + + a new #VteTerminal object + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Places the selected text in the terminal in the #GDK_SELECTION_CLIPBOARD +selection. + Use vte_terminal_copy_clipboard_format() with %VTE_FORMAT_TEXT + instead. + + + + + + + a #VteTerminal + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Sends the contents of the #GDK_SELECTION_CLIPBOARD selection to the +terminal's child. It's called on paste menu item, or when +user presses Shift+Insert. + + + + + + + a #VteTerminal + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Places the selected text in the terminal in the #GDK_SELECTION_CLIPBOARD +selection. + Use vte_terminal_copy_clipboard_format() with %VTE_FORMAT_TEXT + instead. + + + + + + + a #VteTerminal + + + + + + Places the selected text in the terminal in the #GDK_SELECTION_CLIPBOARD +selection in the form specified by @format. + +For all formats, the selection data (see #GtkSelectionData) will include the +text targets (see gtk_target_list_add_text_targets() and +gtk_selection_data_targets_includes_text()). For %VTE_FORMAT_HTML, +the selection will also include the "text/html" target, which when requested, +returns the HTML data in UTF-16 with a U+FEFF BYTE ORDER MARK character at +the start. + + + + + + + a #VteTerminal + + + + a #VteFormat + + + + + + Places the selected text in the terminal in the #GDK_SELECTION_PRIMARY +selection. + + + + + + + a #VteTerminal + + + + + + This function does nothing. + Use vte_terminal_event_check_regex_simple() instead. + + + %FALSE + + + + + a #VteTerminal + + + + a #GdkEvent + + + + an array of #GRegex + + + + + + number of items in @regexes + + + + the #GRegexMatchFlags to use when matching the regexes + + + + a location to store the matches + + + + + + + + Checks each regex in @regexes if the text in and around the position of +the event matches the regular expressions. If a match exists, the matched +text is stored in @matches at the position of the regex in @regexes; otherwise +%NULL is stored there. + + + %TRUE iff any of the regexes produced a match + + + + + a #VteTerminal + + + + a #GdkEvent + + + + an array of #VteRegex + + + + + + number of items in @regexes + + + + PCRE2 match flags, or 0 + + + + a location to store the matches + + + + + + + + Interprets @data as if it were data received from a child process. This +can either be used to drive the terminal without a child process, or just +to mess with your users. + + + + + + + a #VteTerminal + + + + a string in the terminal's current encoding + + + + + + the length of the string, or -1 to use the full length or a nul-terminated string + + + + + + Sends a block of UTF-8 text to the child as if it were entered by the user +at the keyboard. + + + + + + + a #VteTerminal + + + + data to send to the child + + + + + + length of @text in bytes, or -1 if @text is NUL-terminated + + + + + + Sends a block of binary data to the child. + + + + + + + a #VteTerminal + + + + data to send to the child + + + + + + length of @data + + + + + + Checks whether or not the terminal will attempt to draw bold text, +either by using a bold font variant or by repainting text with a different +offset. + + + %TRUE if bolding is enabled, %FALSE if not + + + + + a #VteTerminal + + + + + + Checks whether or not hyperlinks (OSC 8 escape sequence) are allowed. + + + %TRUE if hyperlinks are enabled, %FALSE if not + + + + + a #VteTerminal + + + + + + Checks whether or not the terminal will beep when the child outputs the +"bl" sequence. + + + %TRUE if audible bell is enabled, %FALSE if not + + + + + a #VteTerminal + + + + + + Checks whether the SGR 1 attribute also switches to the bright counterpart +of the first 8 palette colors, in addition to making them bold (legacy behavior) +or if SGR 1 only enables bold and leaves the color intact. + + + %TRUE if bold also enables bright, %FALSE if not + + + + + a #VteTerminal + + + + + + + + the terminal's cell height scale + + + + + a #VteTerminal + + + + + + + + the terminal's cell width scale + + + + + a #VteTerminal + + + + + + + + the height of a character cell + +Note that this method should rather be called vte_terminal_get_cell_height, +because the return value takes cell-height-scale into account. + + + + + a #VteTerminal + + + + + + + + the width of a character cell + +Note that this method should rather be called vte_terminal_get_cell_width, +because the return value takes cell-width-scale into account. + + + + + a #VteTerminal + + + + + + Returns whether ambiguous-width characters are narrow or wide. +(Note that when using a non-UTF-8 encoding set via vte_terminal_set_encoding(), +the width of ambiguous-width characters is fixed and determined by the encoding +itself.) + + + 1 if ambiguous-width characters are narrow, or 2 if they are wide + + + + + a #VteTerminal + + + + + + Returns the background colour, as used by @terminal when +drawing the background, which may be different from +the color set by vte_terminal_set_color_background(). + +Note: you must only call this function while handling the +GtkWidget::draw signal. + +This function is rarely useful. One use for it is if you disable +drawing the background (see vte_terminal_set_clear_background()) +and then need to draw the background yourself. + + + + + + + a #VteTerminal + + + + a location to store a #GdbRGBA color + + + + + + + + the number of columns + + + + + a #VteTerminal + + + + + + + + the URI of the current directory of the + process running in the terminal, or %NULL + + + + + a #VteTerminal + + + + + + + + the URI of the current file the + process running in the terminal is operating on, or %NULL if + not set + + + + + a #VteTerminal + + + + + + Returns the currently set cursor blink mode. + + + cursor blink mode. + + + + + a #VteTerminal + + + + + + Reads the location of the insertion cursor and returns it. The row +coordinate is absolute. + +This method is unaware of BiDi. The returned column is logical column. + + + + + + + a #VteTerminal + + + + a location to store the column, or %NULL + + + + a location to store the row, or %NULL + + + + + + Returns the currently set cursor shape. + + + cursor shape. + + + + + a #VteTerminal + + + + + + Checks whether the terminal performs bidirectional text rendering. + + + %TRUE if BiDi is enabled, %FALSE if not + + + + + a #VteTerminal + + + + + + Checks whether the terminal shapes Arabic text. + + + %TRUE if Arabic shaping is enabled, %FALSE if not + + + + + a #VteTerminal + + + + + + Determines the name of the encoding in which the terminal expects data to be +encoded, or %NULL if UTF-8 is in use. + Support for non-UTF-8 is deprecated. + + + the current encoding for the terminal + + + + + a #VteTerminal + + + + + + Queries the terminal for information about the fonts which will be +used to draw text in the terminal. The actual font takes the font scale +into account, this is not reflected in the return value, the unscaled +font is returned. + + + a #PangoFontDescription describing the font the +terminal uses to render text at the default font scale of 1.0. + + + + + a #VteTerminal + + + + + + + + the terminal's font scale + + + + + a #VteTerminal + + + + + + Fills in some @hints from @terminal's geometry. The hints +filled are those covered by the %GDK_HINT_RESIZE_INC, +%GDK_HINT_MIN_SIZE and %GDK_HINT_BASE_SIZE flags. + +See gtk_window_set_geometry_hints() for more information. + +@terminal must be realized (see gtk_widget_get_realized()). + + + + + + + a #VteTerminal + + + + a #GdkGeometry to fill in + + + + the minimum number of rows to request + + + + the minimum number of columns to request + + + + + + Checks if the terminal currently contains selected text. Note that this +is different from determining if the terminal is the owner of any +#GtkClipboard items. + + + %TRUE if part of the text in the terminal is selected. + + + + + a #VteTerminal + + + + + + + + %NULL + + + + + a #VteTerminal + + + + + + Returns whether the terminal allow user input. + + + + + + + a #VteTerminal + + + + + + Determines the value of the terminal's mouse autohide setting. When +autohiding is enabled, the mouse cursor will be hidden when the user presses +a key and shown when the user moves the mouse. This setting can be changed +using vte_terminal_set_mouse_autohide(). + + + %TRUE if autohiding is enabled, %FALSE if not + + + + + a #VteTerminal + + + + + + Returns the #VtePty of @terminal. + + + a #VtePty, or %NULL + + + + + a #VteTerminal + + + + + + Checks whether or not the terminal will rewrap its contents upon resize. + + + %TRUE if rewrapping is enabled, %FALSE if not + + + + + a #VteTerminal + + + + + + + + the number of rows + + + + + a #VteTerminal + + + + + + + + whether or not the terminal will forcibly scroll to the bottom of +the viewable history when the user presses a key. Modifier keys do not +trigger this behavior. + + + + + a #VteTerminal + + + + + + + + whether or not the terminal will forcibly scroll to the bottom of +the viewable history when the new data is received from the child. + + + + + a #VteTerminal + + + + + + + + length of the scrollback buffer used by the terminal. +A negative value means "infinite scrollback". + + + + + a #VteTerminal + + + + + + Extracts a view of the visible part of the terminal. If @is_selected is not +%NULL, characters will only be read if @is_selected returns %TRUE after being +passed the column and row, respectively. A #VteCharAttributes structure +is added to @attributes for each byte added to the returned string detailing +the character's position, colors, and other characteristics. + +This method is unaware of BiDi. The columns returned in @attributes are +logical columns. + + + a newly allocated text string, or %NULL. + + + + + a #VteTerminal + + + + a #VteSelectionFunc callback + + + + user data to be passed to the callback + + + + location for storing text attributes + + + + + + + + Checks whether or not the terminal will allow blinking text. + + + the blinking setting + + + + + a #VteTerminal + + + + + + Extracts a view of the visible part of the terminal. If @is_selected is not +%NULL, characters will only be read if @is_selected returns %TRUE after being +passed the column and row, respectively. A #VteCharAttributes structure +is added to @attributes for each byte added to the returned string detailing +the character's position, colors, and other characteristics. + +This method is unaware of BiDi. The columns returned in @attributes are +logical columns. + Use vte_terminal_get_text() instead. + + + a newly allocated text string, or %NULL. + + + + + a #VteTerminal + + + + a #VteSelectionFunc callback + + + + user data to be passed to the callback + + + + location for storing text attributes + + + + + + + + Extracts a view of the visible part of the terminal. If @is_selected is not +%NULL, characters will only be read if @is_selected returns %TRUE after being +passed the column and row, respectively. A #VteCharAttributes structure +is added to @attributes for each byte added to the returned string detailing +the character's position, colors, and other characteristics. The +entire scrollback buffer is scanned, so it is possible to read the entire +contents of the buffer using this function. + +This method is unaware of BiDi. The columns passed in @start_col and @end_row, +and returned in @attributes are logical columns. + + + a newly allocated text string, or %NULL. + + + + + a #VteTerminal + + + + first row to search for data + + + + first column to search for data + + + + last row to search for data + + + + last column to search for data + + + + a #VteSelectionFunc callback + + + + user data to be passed to the callback + + + + location for storing text attributes + + + + + + + + + + the window title, or %NULL + + + + + a #VteTerminal + + + + + + Returns the set of characters which will be considered parts of a word +when doing word-wise selection, in addition to the default which only +considers alphanumeric characters part of a word. + +If %NULL, a built-in set is used. + + + a string, or %NULL + + + + + a #VteTerminal + + + + + + Returns a nonempty string: the target of the explicit hyperlink (printed using the OSC 8 +escape sequence) at the position of the event, or %NULL. + +Proper use of the escape sequence should result in URI-encoded URIs with a proper scheme +like "http://", "https://", "file://", "mailto:" etc. This is, however, not enforced by VTE. +The caller must tolerate the returned string potentially not being a valid URI. + + + a newly allocated string containing the target of the hyperlink + + + + + a #VteTerminal + + + + a #GdkEvent + + + + + + Adds the regular expression @regex to the list of matching expressions. When the +user moves the mouse cursor over a section of displayed text which matches +this expression, the text will be highlighted. + Use vte_terminal_match_add_regex() or vte_terminal_match_add_regex_full() instead. + + + an integer associated with this expression, or -1 if @gregex could not be + transformed into a #VteRegex or @gflags were incompatible + + + + + a #VteTerminal + + + + a #GRegex + + + + the #GRegexMatchFlags to use when matching the regex + + + + + + Adds the regular expression @regex to the list of matching expressions. When the +user moves the mouse cursor over a section of displayed text which matches +this expression, the text will be highlighted. + + + an integer associated with this expression + + + + + a #VteTerminal + + + + a #VteRegex + + + + PCRE2 match flags, or 0 + + + + + + Checks if the text in and around the specified position matches any of the +regular expressions previously set using vte_terminal_match_add(). If a +match exists, the text string is returned and if @tag is not %NULL, the number +associated with the matched regular expression will be stored in @tag. + +If more than one regular expression has been set with +vte_terminal_match_add(), then expressions are checked in the order in +which they were added. + Use vte_terminal_match_check_event() instead. + + + a newly allocated string which matches one of the previously + set regular expressions + + + + + a #VteTerminal + + + + the text column + + + + the text row + + + + a location to store the tag, or %NULL + + + + + + Checks if the text in and around the position of the event matches any of the +regular expressions previously set using vte_terminal_match_add(). If a +match exists, the text string is returned and if @tag is not %NULL, the number +associated with the matched regular expression will be stored in @tag. + +If more than one regular expression has been set with +vte_terminal_match_add(), then expressions are checked in the order in +which they were added. + + + a newly allocated string which matches one of the previously + set regular expressions + + + + + a #VteTerminal + + + + a #GdkEvent + + + + a location to store the tag, or %NULL + + + + + + Removes the regular expression which is associated with the given @tag from +the list of expressions which the terminal will highlight when the user +moves the mouse cursor over matching text. + + + + + + + a #VteTerminal + + + + the tag of the regex to remove + + + + + + Clears the list of regular expressions the terminal uses to highlight text +when the user moves the mouse cursor. + + + + + + + a #VteTerminal + + + + + + Sets which cursor the terminal will use if the pointer is over the pattern +specified by @tag. The terminal keeps a reference to @cursor. + Use vte_terminal_match_set_cursor_name() instead. + + + + + + + a #VteTerminal + + + + the tag of the regex which should use the specified cursor + + + + the #GdkCursor which the terminal should use when the pattern is + highlighted, or %NULL to use the standard cursor + + + + + + Sets which cursor the terminal will use if the pointer is over the pattern +specified by @tag. + + + + + + + a #VteTerminal + + + + the tag of the regex which should use the specified cursor + + + + the name of the cursor + + + + + + Sets which cursor the terminal will use if the pointer is over the pattern +specified by @tag. + Use vte_terminal_match_set_cursor_name() instead. + + + + + + + a #VteTerminal + + + + the tag of the regex which should use the specified cursor + + + + a #GdkCursorType + + + + + + Sends the contents of the #GDK_SELECTION_CLIPBOARD selection to the +terminal's child. It's called on paste menu item, or when +user presses Shift+Insert. + + + + + + + a #VteTerminal + + + + + + Sends the contents of the #GDK_SELECTION_PRIMARY selection to the terminal's +child. The terminal will call also paste the +#GDK_SELECTION_PRIMARY selection when the user clicks with the the second +mouse button. + + + + + + + a #VteTerminal + + + + + + Creates a new #VtePty, and sets the emulation property +from #VteTerminal:emulation. + +See vte_pty_new() for more information. + + + a new #VtePty + + + + + a #VteTerminal + + + + flags from #VtePtyFlags + + + + a #GCancellable, or %NULL + + + + + + Resets as much of the terminal's internal state as possible, discarding any +unprocessed input data, resetting character attributes, cursor state, +national character set state, status line, terminal modes (insert/delete), +selection state, and encoding. + + + + + + + a #VteTerminal + + + + whether to reset tabstops + + + + whether to empty the terminal's scrollback buffer + + + + + + Searches the next string matching the search regex set with +vte_terminal_search_set_regex(). + + + %TRUE if a match was found + + + + + a #VteTerminal + + + + + + Searches the previous string matching the search regex set with +vte_terminal_search_set_regex(). + + + %TRUE if a match was found + + + + + a #VteTerminal + + + + + + use vte_terminal_search_get_regex() instead. + + + %NULL + + + + + a #VteTerminal + + + + + + + + the search #VteRegex regex set in @terminal, or %NULL + + + + + a #VteTerminal + + + + + + + + whether searching will wrap around + + + + + a #VteTerminal + + + + + + Sets the #GRegex regex to search for. Unsets the search regex when passed %NULL. + use vte_terminal_search_set_regex() instead. + + + + + + + a #VteTerminal + + + + a #GRegex, or %NULL + + + + flags from #GRegexMatchFlags + + + + + + Sets the regex to search for. Unsets the search regex when passed %NULL. + + + + + + + a #VteTerminal + + + + a #VteRegex, or %NULL + + + + PCRE2 match flags, or 0 + + + + + + Sets whether search should wrap around to the beginning of the +terminal content when reaching its end. + + + + + + + a #VteTerminal + + + + whether search should wrap + + + + + + Selects all text within the terminal (including the scrollback buffer). + + + + + + + a #VteTerminal + + + + + + Controls whether or not the terminal will attempt to draw bold text, +either by using a bold font variant or by repainting text with a different +offset. + + + + + + + a #VteTerminal + + + + %TRUE if the terminal should attempt to draw bold text + + + + + + Controls whether or not hyperlinks (OSC 8 escape sequence) are allowed. + + + + + + + a #VteTerminal + + + + %TRUE if the terminal should allow hyperlinks + + + + + + Controls whether or not the terminal will beep when the child outputs the +"bl" sequence. + + + + + + + a #VteTerminal + + + + %TRUE if the terminal should beep + + + + + + Modifies the terminal's backspace key binding, which controls what +string or control sequence the terminal sends to its child when the user +presses the backspace key. + + + + + + + a #VteTerminal + + + + a #VteEraseBinding for the backspace key + + + + + + Sets whether the SGR 1 attribute also switches to the bright counterpart +of the first 8 palette colors, in addition to making them bold (legacy behavior) +or if SGR 1 only enables bold and leaves the color intact. + + + + + + + a #VteTerminal + + + + %TRUE if bold should also enable bright + + + + + + Sets the terminal's cell height scale to @scale. + +This can be used to increase the line spacing. (The font's height is not affected.) +Valid values go from 1.0 (default) to 2.0 ("double spacing"). + + + + + + + a #VteTerminal + + + + the cell height scale + + + + + + Sets the terminal's cell width scale to @scale. + +This can be used to increase the letter spacing. (The font's width is not affected.) +Valid values go from 1.0 (default) to 2.0. + + + + + + + a #VteTerminal + + + + the cell width scale + + + + + + This setting controls whether ambiguous-width characters are narrow or wide. +(Note that when using a non-UTF-8 encoding set via vte_terminal_set_encoding(), +the width of ambiguous-width characters is fixed and determined by the encoding +itself.) + + + + + + + a #VteTerminal + + + + either 1 (narrow) or 2 (wide) + + + + + + Sets whether to paint the background with the background colour. +The default is %TRUE. + +This function is rarely useful. One use for it is to add a background +image to the terminal. + + + + + + + a #VteTerminal + + + + + + + + + Sets the background color for text which does not have a specific background +color assigned. Only has effect when no background image is set and when +the terminal is not transparent. + + + + + + + a #VteTerminal + + + + the new background color + + + + + + Sets the color used to draw bold text in the default foreground color. +If @bold is %NULL then the default color is used. + + + + + + + a #VteTerminal + + + + the new bold color or %NULL + + + + + + Sets the background color for text which is under the cursor. If %NULL, text +under the cursor will be drawn with foreground and background colors +reversed. + + + + + + + a #VteTerminal + + + + the new color to use for the text cursor, or %NULL + + + + + + Sets the foreground color for text which is under the cursor. If %NULL, text +under the cursor will be drawn with foreground and background colors +reversed. + + + + + + + a #VteTerminal + + + + the new color to use for the text cursor, or %NULL + + + + + + Sets the foreground color used to draw normal text. + + + + + + + a #VteTerminal + + + + the new foreground color + + + + + + Sets the background color for text which is highlighted. If %NULL, +it is unset. If neither highlight background nor highlight foreground are set, +highlighted text (which is usually highlighted because it is selected) will +be drawn with foreground and background colors reversed. + + + + + + + a #VteTerminal + + + + the new color to use for highlighted text, or %NULL + + + + + + Sets the foreground color for text which is highlighted. If %NULL, +it is unset. If neither highlight background nor highlight foreground are set, +highlighted text (which is usually highlighted because it is selected) will +be drawn with foreground and background colors reversed. + + + + + + + a #VteTerminal + + + + the new color to use for highlighted text, or %NULL + + + + + + @palette specifies the new values for the 256 palette colors: 8 standard colors, +their 8 bright counterparts, 6x6x6 color cube, and 24 grayscale colors. +Omitted entries will default to a hardcoded value. + +@palette_size must be 0, 8, 16, 232 or 256. + +If @foreground is %NULL and @palette_size is greater than 0, the new foreground +color is taken from @palette[7]. If @background is %NULL and @palette_size is +greater than 0, the new background color is taken from @palette[0]. + + + + + + + a #VteTerminal + + + + the new foreground color, or %NULL + + + + the new background color, or %NULL + + + + the color palette + + + + + + the number of entries in @palette + + + + + + Sets whether or not the cursor will blink. Using %VTE_CURSOR_BLINK_SYSTEM +will use the #GtkSettings::gtk-cursor-blink setting. + + + + + + + a #VteTerminal + + + + the #VteCursorBlinkMode to use + + + + + + Sets the shape of the cursor drawn. + + + + + + + a #VteTerminal + + + + the #VteCursorShape to use + + + + + + Reset the terminal palette to reasonable compiled-in default color. + + + + + + + a #VteTerminal + + + + + + Modifies the terminal's delete key binding, which controls what +string or control sequence the terminal sends to its child when the user +presses the delete key. + + + + + + + a #VteTerminal + + + + a #VteEraseBinding for the delete key + + + + + + Controls whether or not the terminal will perform bidirectional text rendering. + + + + + + + a #VteTerminal + + + + %TRUE to enable BiDi support + + + + + + Controls whether or not the terminal will shape Arabic text. + + + + + + + a #VteTerminal + + + + %TRUE to enable Arabic shaping + + + + + + Changes the encoding the terminal will expect data from the child to +be encoded with. For certain terminal types, applications executing in the +terminal can change the encoding. If @codeset is %NULL, it uses "UTF-8". + +Note: Support for non-UTF-8 is deprecated and may get removed altogether. +Instead of this function, you should use a wrapper like luit(1) when +spawning the child process. + Support for non-UTF-8 is deprecated. + + + %TRUE if the encoding could be changed to the specified one, + or %FALSE with @error set to %G_CONVERT_ERROR_NO_CONVERSION. + + + + + a #VteTerminal + + + + a valid #GIConv target, or %NULL to use UTF-8 + + + + + + Sets the font used for rendering all text displayed by the terminal, +overriding any fonts set using gtk_widget_modify_font(). The terminal +will immediately attempt to load the desired font, retrieve its +metrics, and attempt to resize itself to keep the same number of rows +and columns. The font scale is applied to the specified font. + + + + + + + a #VteTerminal + + + + a #PangoFontDescription for the desired font, or %NULL + + + + + + Sets the terminal's font scale to @scale. + + + + + + + a #VteTerminal + + + + the font scale + + + + + + Sets @terminal as @window's geometry widget. See +gtk_window_set_geometry_hints() for more information. + +@terminal must be realized (see gtk_widget_get_realized()). + + + + + + + a #VteTerminal + + + + a #GtkWindow + + + + + + Enables or disables user input. When user input is disabled, +the terminal's child will not receive any key press, or mouse button +press or motion events sent to it. + + + + + + + a #VteTerminal + + + + whether to enable user input + + + + + + Changes the value of the terminal's mouse autohide setting. When autohiding +is enabled, the mouse cursor will be hidden when the user presses a key and +shown when the user moves the mouse. This setting can be read using +vte_terminal_get_mouse_autohide(). + + + + + + + a #VteTerminal + + + + whether the mouse pointer should autohide + + + + + + Sets @pty as the PTY to use in @terminal. +Use %NULL to unset the PTY. + + + + + + + a #VteTerminal + + + + a #VtePty, or %NULL + + + + + + Controls whether or not the terminal will rewrap its contents, including +the scrollback history, whenever the terminal's width changes. + + + + + + + a #VteTerminal + + + + %TRUE if the terminal should rewrap on resize + + + + + + Controls whether or not the terminal will forcibly scroll to the bottom of +the viewable history when the user presses a key. Modifier keys do not +trigger this behavior. + + + + + + + a #VteTerminal + + + + whether the terminal should scroll on keystrokes + + + + + + Controls whether or not the terminal will forcibly scroll to the bottom of +the viewable history when the new data is received from the child. + + + + + + + a #VteTerminal + + + + whether the terminal should scroll on output + + + + + + Sets the length of the scrollback buffer used by the terminal. The size of +the scrollback buffer will be set to the larger of this value and the number +of visible rows the widget can display, so 0 can safely be used to disable +scrollback. + +A negative value means "infinite scrollback". + +Note that this setting only affects the normal screen buffer. +No scrollback is allowed on the alternate screen buffer. + + + + + + + a #VteTerminal + + + + the length of the history buffer + + + + + + Attempts to change the terminal's size in terms of rows and columns. If +the attempt succeeds, the widget will resize itself to the proper size. + + + + + + + a #VteTerminal + + + + the desired number of columns + + + + the desired number of rows + + + + + + Controls whether or not the terminal will allow blinking text. + + + + + + + a #VteTerminal + + + + the #VteTextBlinkMode to use + + + + + + With this function you can provide a set of characters which will +be considered parts of a word when doing word-wise selection, in +addition to the default which only considers alphanumeric characters +part of a word. + +The characters in @exceptions must be non-alphanumeric, each character +must occur only once, and if @exceptions contains the character +U+002D HYPHEN-MINUS, it must be at the start of the string. + +Use %NULL to reset the set of exception characters to the default. + + + + + + + a #VteTerminal + + + + a string of ASCII punctuation characters, or %NULL + + + + + + A convenience function that wraps creating the #VtePty and spawning +the child process on it. See vte_pty_new_sync(), vte_pty_spawn_async(), +and vte_pty_spawn_finish() for more information. + +When the operation is finished successfully, @callback will be called +with the child #GPid, and a %NULL #GError. The child PID will already be +watched via vte_terminal_watch_child(). + +When the operation fails, @callback will be called with a -1 #GPid, +and a non-%NULL #GError containing the error information. + +Note that if @terminal has been destroyed before the operation is called, +@callback will be called with a %NULL @terminal; you must not do anything +in the callback besides freeing any resources associated with @user_data, +but taking care not to access the now-destroyed #VteTerminal. Note that +in this case, if spawning was successful, the child process will be aborted +automatically. + +Beginning with 0.52, sets PWD to @working_directory in order to preserve symlink components. +The caller should also make sure that symlinks were preserved while constructing the value of @working_directory, +e.g. by using vte_terminal_get_current_directory_uri(), g_get_current_dir() or get_current_dir_name(). + + + + + + + a #VteTerminal + + + + flags from #VtePtyFlags + + + + the name of a directory the command should start + in, or %NULL to use the current working directory + + + + child's argument vector + + + + + + a list of environment + variables to be added to the environment before starting the process, or %NULL + + + + + + flags from #GSpawnFlags + + + + an extra child setup function to run in the child just before exec(), or %NULL + + + + user data for @child_setup, or %NULL + + + + a #GDestroyNotify for @child_setup_data, or %NULL + + + + a timeout value in ms, or -1 to wait indefinitely + + + + a #GCancellable, or %NULL + + + + a #VteTerminalSpawnAsyncCallback, or %NULL + + + + user data for @callback, or %NULL + + + + + + Starts the specified command under a newly-allocated controlling +pseudo-terminal. The @argv and @envv lists should be %NULL-terminated. +The "TERM" environment variable is automatically set to a default value, +but can be overridden from @envv. +@pty_flags controls logging the session to the specified system log files. + +Note that %G_SPAWN_DO_NOT_REAP_CHILD will always be added to @spawn_flags. + +Note that all open file descriptors will be closed in the child. If you want +to keep some file descriptor open for use in the child process, you need to +use a child setup function that unsets the FD_CLOEXEC flag on that file +descriptor. + +See vte_pty_new(), g_spawn_async() and vte_terminal_watch_child() for more information. + +Beginning with 0.52, sets PWD to @working_directory in order to preserve symlink components. +The caller should also make sure that symlinks were preserved while constructing the value of @working_directory, +e.g. by using vte_terminal_get_current_directory_uri(), g_get_current_dir() or get_current_dir_name(). + Use vte_terminal_spawn_async() instead. + + + %TRUE on success, or %FALSE on error with @error filled in + + + + + a #VteTerminal + + + + flags from #VtePtyFlags + + + + the name of a directory the command should start + in, or %NULL to use the current working directory + + + + child's argument vector + + + + + + a list of environment + variables to be added to the environment before starting the process, or %NULL + + + + + + flags from #GSpawnFlags + + + + an extra child setup function to run in the child just before exec(), or %NULL + + + + user data for @child_setup + + + + a location to store the child PID, or %NULL + + + + a #GCancellable, or %NULL + + + + + + Clears the current selection. + + + + + + + a #VteTerminal + + + + + + Watches @child_pid. When the process exists, the #VteTerminal::child-exited +signal will be called with the child's exit status. + +Prior to calling this function, a #VtePty must have been set in @terminal +using vte_terminal_set_pty(). +When the child exits, the terminal's #VtePty will be set to %NULL. + +Note: g_child_watch_add() or g_child_watch_add_full() must not have +been called for @child_pid, nor a #GSource for it been created with +g_child_watch_source_new(). + +Note: when using the g_spawn_async() family of functions, +the %G_SPAWN_DO_NOT_REAP_CHILD flag MUST have been passed. + + + + + + + a #VteTerminal + + + + a #GPid + + + + + + Write contents of the current contents of @terminal (including any +scrollback history) to @stream according to @flags. + +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 @error. + +This is a synchronous operation and will make the widget (and input +processing) during the write operation, which may take a long time +depending on scrollback history and @stream availability for writing. + + + %TRUE on success, %FALSE if there was an error + + + + + a #VteTerminal + + + + a #GOutputStream to write to + + + + a set of #VteWriteFlags + + + + a #GCancellable object, or %NULL + + + + + + Controls whether or not the terminal will attempt to draw bold text. +This may happen either by using a bold font variant, or by +repainting text with a different offset. + + + + Controls whether or not hyperlinks (OSC 8 escape sequence) are recognized and displayed. + + + + Controls whether or not the terminal will beep when the child outputs the +"bl" sequence. + + + + Controls what string or control sequence the terminal sends to its child +when the user presses the backspace key. + + + + Whether the SGR 1 attribute also switches to the bright counterpart +of the first 8 palette colors, in addition to making them bold (legacy behavior) +or if SGR 1 only enables bold and leaves the color intact. + + + + Scale factor for the cell height, to increase line spacing. (The font's height is not affected.) + + + + Scale factor for the cell width, to increase letter spacing. (The font's width is not affected.) + + + + This setting controls whether ambiguous-width characters are narrow or wide. +(Note that when using a non-UTF-8 encoding set via vte_terminal_set_encoding(), +the width of ambiguous-width characters is fixed and determined by the encoding +itself.) + +This setting only takes effect the next time the terminal is reset, either +via escape sequence or with vte_terminal_reset(). + + + + The current directory URI, or %NULL if unset. + + + + The current file URI, or %NULL if unset. + + + + Sets whether or not the cursor will blink. Using %VTE_CURSOR_BLINK_SYSTEM +will use the #GtkSettings::gtk-cursor-blink setting. + + + + Controls the shape of the cursor. + + + + Controls what string or control sequence the terminal sends to its child +when the user presses the delete key. + + + + Controls whether or not the terminal will perform bidirectional text rendering. + + + + Controls whether or not the terminal will shape Arabic text. + + + + Controls the encoding the terminal will expect data from the child to +be encoded with. For certain terminal types, applications executing in the +terminal can change the encoding. The default is defined by the +application's locale settings. + Instead of using this, you should use a tool like + luit(1) when support for non-UTF-8 is required + + + + Specifies the font used for rendering all text displayed by the terminal, +overriding any fonts set using gtk_widget_modify_font(). The terminal +will immediately attempt to load the desired font, retrieve its +metrics, and attempt to resize itself to keep the same number of rows +and columns. + + + + The terminal's font scale. + + + + The currently hovered hyperlink URI, or %NULL if unset. + + + + This property is always %NULL. + + + + Controls whether the terminal allows user input. When user input is disabled, +key press and mouse button press and motion events are not sent to the +terminal's child. + + + + Controls the value of the terminal's mouse autohide setting. When autohiding +is enabled, the mouse cursor will be hidden when the user presses a key and +shown when the user moves the mouse. + + + + The PTY object for the terminal. + + + + Controls whether or not the terminal will rewrap its contents, including +the scrollback buffer, whenever the terminal's width changes. + + + + Controls whether or not the terminal will forcibly scroll to the bottom of +the viewable history when the user presses a key. Modifier keys do not +trigger this behavior. + + + + Controls whether or not the terminal will forcibly scroll to the bottom of +the viewable history when the new data is received from the child. + + + + The length of the scrollback buffer used by the terminal. The size of +the scrollback buffer will be set to the larger of this value and the number +of visible rows the widget can display, so 0 can safely be used to disable +scrollback. Note that this setting only affects the normal screen buffer. +For terminal types which have an alternate screen buffer, no scrollback is +allowed on the alternate screen buffer. + + + + Controls whether or not the terminal will allow blinking text. + + + + The terminal's title. + + + + The set of characters which will be considered parts of a word +when doing word-wise selection, in addition to the default which only +considers alphanumeric characters part of a word. + +If %NULL, a built-in set is used. + + + + + + + + + + + + This signal is emitted when the a child sends a bell request to the +terminal. + + + + + + Emitted whenever the cell size changes, e.g. due to a change in +font, font-scale or cell-width/height-scale. + +Note that this signal should rather be called "cell-size-changed". + + + + + + the new character cell width + + + + the new character cell height + + + + + + This signal is emitted when the terminal detects that a child +watched using vte_terminal_watch_child() has exited. + + + + + + the child's exit status + + + + + + Emitted whenever the terminal receives input from the user and +prepares to send it to the child process. The signal is emitted even +when there is no child process. + + + + + + a string of text + + + + the length of that string of text + + + + + + Emitted whenever the visible appearance of the terminal has changed. +Used primarily by #VteTerminalAccessible. + + + + + + Emitted whenever vte_terminal_copy_clipboard() is called. + + + + + + Emitted when the current directory URI is modified. + + + + + + Emitted when the current file URI is modified. + + + + + + Emitted whenever the cursor moves to a new character cell. Used +primarily by #VteTerminalAccessible. + + + + + + Emitted when the user hits the '-' key while holding the Control key. + + + + + + Emitted at the child application's request. + + + + + + Emitted whenever the terminal's current encoding has changed. + +Note: support for non-UTF-8 is deprecated. + + + + + + Emitted when the terminal receives an end-of-file from a child which +is running in the terminal. This signal is frequently (but not +always) emitted with a #VteTerminal::child-exited signal. + + + + + + Emitted when the hovered hyperlink changes. + +@uri and @bbox are owned by VTE, must not be modified, and might +change after the signal handlers returns. + +The signal is not re-emitted when the bounding box changes for the +same hyperlink. This might change in a future VTE version without notice. + + + + + + the nonempty target URI under the mouse, or NULL + + + + the bounding box of the hyperlink anchor text, or NULL + + + + + + This signal is never emitted. + + + + + + Emitted at the child application's request. + + + + + + Emitted when the user hits the '+' key while holding the Control key. + + + + + + Emitted at the child application's request. + + + + + + Emitted at the child application's request. + + + + + + Emitted at the child application's request. + + + + + + the terminal's desired location, X coordinate + + + + the terminal's desired location, Y coordinate + + + + + + Emitted whenever vte_terminal_paste_clipboard() is called. + + + + + + Emitted at the child application's request. + + + + + + Emitted at the child application's request. + + + + + + Emitted at the child application's request. + + + + + + the desired number of columns + + + + the desired number of rows + + + + + + Emitted at the child application's request. + + + + + + Emitted whenever the contents of terminal's selection changes. + + + + + + An internal signal used for communication between the terminal and +its accessibility peer. May not be emitted under certain +circumstances. + + + + + + An internal signal used for communication between the terminal and +its accessibility peer. May not be emitted under certain +circumstances. + + + + + + An internal signal used for communication between the terminal and +its accessibility peer. May not be emitted under certain +circumstances. + + + + + + An internal signal used for communication between the terminal and +its accessibility peer. May not be emitted under certain +circumstances. + + + + + + the number of lines scrolled + + + + + + Emitted when the terminal's %window_title field is modified. + + + + + + + All of these fields should be considered read-only, except for derived classes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #VteTerminal + + + + + + + + + + + + + + a #VteTerminal + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Callback for vte_terminal_spawn_async(). + +On success, @pid contains the PID of the spawned process, and @error +is %NULL. +On failure, @pid is -1 and @error contains the error information. + + + + + + + the #VteTerminal + + + + a #GPid + + + + a #GError, or %NULL + + + + user data that was passed to vte_terminal_spawn_async + + + + + + An enumerated type which can be used to indicate whether the terminal allows +the text contents to be blinked. + + Do not blink the text. + + + Allow blinking text only if the terminal is focused. + + + Allow blinking text only if the terminal is unfocused. + + + Allow blinking text. This is the default. + + + + A flag type to determine how terminal contents should be written +to an output stream. + + Write contents as UTF-8 text. This is the default. + + + + Gets a list of features vte was compiled with. + + + a string with features + + + + + Returns the major version of the VTE library at runtime. +Contrast this with %VTE_MAJOR_VERSION which represents +the version of the VTE library that the code was compiled +with. + + + the major version + + + + + Returns the micro version of the VTE library at runtime. +Contrast this with %VTE_MICRO_VERSION which represents +the version of the VTE library that the code was compiled +with. + + + the micro version + + + + + Returns the minor version of the VTE library at runtime. +Contrast this with %VTE_MINOR_VERSION which represents +the version of the VTE library that the code was compiled +with. + + + the minor version + + + + + Gets the user's shell, or %NULL. In the latter case, the +system default (usually "/bin/sh") should be used. + + + a newly allocated string with the + user's shell, or %NULL + + + + + Error domain for VTE PTY errors. Errors in this domain will be from the #VtePtyError +enumeration. See #GError for more information on error domains. + + the error domain for VTE PTY errors + + + + + + + + + + Sets test flags. This function is only useful for implementing +unit tests for vte itself; it is a no-op in non-debug builds. + + + + + + + flags + + + + + + diff --git a/gir-files/Vulkan-1.0.gir b/gir-files/Vulkan-1.0.gir new file mode 100644 index 0000000..4ca606c --- /dev/null +++ b/gir-files/Vulkan-1.0.gir @@ -0,0 +1,795 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/WebKit2-4.0.gir b/gir-files/WebKit2-4.0.gir new file mode 100644 index 0000000..44e9fa8 --- /dev/null +++ b/gir-files/WebKit2-4.0.gir @@ -0,0 +1,18155 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #WebKitApplicationInfo + + + the newly created #WebKitApplicationInfo. + + + + + Get the name of the application. If webkit_application_info_set_name() hasn't been +called with a valid name, this returns g_get_prgname(). + + + the application name + + + + + a #WebKitApplicationInfo + + + + + + Get the application version previously set with webkit_application_info_set_version(). + + + + + + + a #WebKitApplicationInfo + + + + return location for the major version number + + + + return location for the minor version number + + + + return location for the micro version number + + + + + + Atomically increments the reference count of @info by one. This +function is MT-safe and may be called from any thread. + + + The passed in #WebKitApplicationInfo + + + + + a #WebKitApplicationInfo + + + + + + Set the name of the application. If not provided, or %NULL is passed, +g_get_prgname() will be used. + + + + + + + a #WebKitApplicationInfo + + + + the application name + + + + + + Set the application version. If the application doesn't use the format +major.minor.micro you can pass 0 as the micro to use major.minor, or pass +0 as both micro and minor to use only major number. Any other format must +be converted to major.minor.micro so that it can be used in version comparisons. + + + + + + + a #WebKitApplicationInfo + + + + the major version number + + + + the minor version number + + + + the micro version number + + + + + + Atomically decrements the reference count of @info by one. If the +reference count drops to 0, all memory allocated by the #WebKitApplicationInfo is +released. This function is MT-safe and may be called from any +thread. + + + + + + + a #WebKitApplicationInfo + + + + + + + + + Authenticate the #WebKitAuthenticationRequest using the #WebKitCredential +supplied. To continue without credentials, pass %NULL as @credential. + + + + + + + a #WebKitAuthenticationRequest + + + + A #WebKitCredential, or %NULL + + + + + + Determine whether the authentication method associated with this +#WebKitAuthenticationRequest should allow the storage of credentials. +This will return %FALSE if WebKit doesn't support credential storing +or if private browsing is enabled. + + + %TRUE if WebKit can store credentials or %FALSE otherwise. + + + + + a #WebKitAuthenticationRequest + + + + + + Cancel the authentication challenge. This will also cancel the page loading and result in a +#WebKitWebView::load-failed signal with a #WebKitNetworkError of type %WEBKIT_NETWORK_ERROR_CANCELLED being emitted. + + + + + + + a #WebKitAuthenticationRequest + + + + + + Get the host that this authentication challenge is applicable to. + + + The host of @request. + + + + + a #WebKitAuthenticationRequest + + + + + + Get the port that this authentication challenge is applicable to. + + + The port of @request. + + + + + a #WebKitAuthenticationRequest + + + + + + Get the #WebKitCredential of the proposed authentication challenge that was +stored from a previous session. The client can use this directly for +authentication or construct their own #WebKitCredential. + + + A #WebKitCredential encapsulating credential details +or %NULL if there is no stored credential. + + + + + a #WebKitAuthenticationRequest + + + + + + Get the realm that this authentication challenge is applicable to. + + + The realm of @request. + + + + + a #WebKitAuthenticationRequest + + + + + + Get the authentication scheme of the authentication challenge. + + + The #WebKitAuthenticationScheme of @request. + + + + + a #WebKitAuthenticationRequest + + + + + + Determine whether the authentication challenge is associated with a proxy server rather than an "origin" server. + + + %TRUE if authentication is for a proxy or %FALSE otherwise. + + + + + a #WebKitAuthenticationRequest + + + + + + Determine whether this this is a first attempt or a retry for this authentication challenge. + + + %TRUE if authentication attempt is a retry or %FALSE otherwise. + + + + + a #WebKitAuthenticationRequest + + + + + + + + + + + + This signal is emitted when the user authentication request is +cancelled. It allows the application to dismiss its authentication +dialog in case of page load failure for example. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values representing the authentication scheme. + + The default authentication scheme of WebKit. + + + Basic authentication scheme as defined in RFC 2617. + + + Digest authentication scheme as defined in RFC 2617. + + + HTML Form authentication. + + + NTLM Microsoft proprietary authentication scheme. + + + Negotiate (or SPNEGO) authentication scheme as defined in RFC 4559. + + + Client Certificate Authentication (see RFC 2246). + + + Server Trust Authentication. + + + Authentication scheme unknown. + + + + + + Get the #WebKitAutomationSession previously set with webkit_automation_session_set_application_info(). + + + the #WebKitAutomationSession of @session, or %NULL if no one has been set. + + + + + a #WebKitAutomationSession + + + + + + Get the unique identifier of a #WebKitAutomationSession + + + the unique identifier of @session + + + + + a #WebKitAutomationSession + + + + + + Set the application information to @session. This information will be used by the driver service +to match the requested capabilities with the actual application information. If this information +is not provided to the session when a new automation session is requested, the creation might fail +if the client requested a specific browser name or version. This will not have any effect when called +after the automation session has been fully created, so this must be called in the callback of +#WebKitWebContext::automation-started signal. + + + + + + + a #WebKitAutomationSession + + + + a #WebKitApplicationInfo + + + + + + The session unique identifier. + + + + + + + + + + This signal is emitted when the automation client requests a new +browsing context to interact with it. The callback handler should +return a #WebKitWebView created with #WebKitWebView:is-controlled-by-automation +construct property enabled. The returned #WebKitWebView could be an existing +web view or a new one created and added to a new tab or window. + + a #WebKitWebView widget. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the item that precedes the current item. + + + the #WebKitBackForwardListItem + preceding the current item or %NULL. + + + + + a #WebKitBackForwardList + + + + + + + + a #GList of + items preceding the current item. + + + + + + + a #WebKitBackForwardList + + + + + + + + a #GList of + items preceding the current item limited by @limit. + + + + + + + a #WebKitBackForwardList + + + + the number of items to retrieve + + + + + + Returns the current item in @back_forward_list. + + + a #WebKitBackForwardListItem + or %NULL if @back_forward_list is empty. + + + + + a #WebKitBackForwardList + + + + + + Returns the item that follows the current item. + + + the #WebKitBackForwardListItem + following the current item or %NULL. + + + + + a #WebKitBackForwardList + + + + + + + + a #GList of + items following the current item. + + + + + + + a #WebKitBackForwardList + + + + + + + + a #GList of + items following the current item limited by @limit. + + + + + + + a #WebKitBackForwardList + + + + the number of items to retrieve + + + + + + + + the length of @back_forward_list. + + + + + a #WebKitBackForwardList + + + + + + Returns the item at a given index relative to the current item. + + + the #WebKitBackForwardListItem + located at the specified index relative to the current item or %NULL. + + + + + a #WebKitBackForwardList + + + + the index of the item + + + + + + + + + + + + This signal is emitted when @back_forward_list changes. This happens +when the current item is updated, a new item is added or one or more +items are removed. Note that both @item_added and @items_removed can +%NULL when only the current item is updated. Items are only removed +when the list is cleared or the maximum items limit is reached. + + + + + + the #WebKitBackForwardListItem added or %NULL + + + + a #GList of #WebKitBackForwardListItem<!-- -->s + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + See also webkit_back_forward_list_item_get_uri(). + + + the original URI of @list_item or %NULL + when the original URI is empty. + + + + + a #WebKitBackForwardListItem + + + + + + + + the page title of @list_item or %NULL + when the title is empty. + + + + + a #WebKitBackForwardListItem + + + + + + This URI may differ from the original URI if the page was, +for example, redirected to a new location. +See also webkit_back_forward_list_item_get_original_uri(). + + + the URI of @list_item or %NULL + when the URI is empty. + + + + + a #WebKitBackForwardListItem + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used for determining the #WebKitWebContext cache model. + + Disable the cache completely, which + substantially reduces memory usage. Useful for applications that only + access a single local file, with no navigation to other pages. No remote + resources will be cached. + + + Improve document load speed substantially + by caching a very large number of resources and previously viewed content. + + + A cache model optimized for viewing + a series of local files -- for example, a documentation viewer or a website + designer. WebKit will cache a moderate number of resources. + + + + + + Cancels @request and the input element changes to use the initial color +it has before the request started. +The signal #WebKitColorChooserRequest::finished +is emitted to notify that the request has finished. + + + + + + + a #WebKitColorChooserRequest + + + + + + Finishes @request and the input element keeps the current value of +#WebKitColorChooserRequest:rgba. +The signal #WebKitColorChooserRequest::finished +is emitted to notify that the request has finished. + + + + + + + a #WebKitColorChooserRequest + + + + + + Gets the bounding box of the color input element. + + + + + + + a #WebKitColorChooserRequest + + + + a #GdkRectangle to fill in with the element area + + + + + + Gets the current #GdkRGBA color of @request + + + + + + + a #WebKitColorChooserRequest + + + + a #GdkRGBA to fill in with the current color. + + + + + + Sets the current #GdkRGBA color of @request + + + + + + + a #WebKitFileChooserRequest + + + + a pointer #GdkRGBA + + + + + + + + + + + + + + + Emitted when the @request finishes. This signal can be emitted because the +user completed the @request calling webkit_color_chooser_request_finish(), +or cancelled it with webkit_color_chooser_request_cancel() or because the +color input element is removed from the DOM. + + + + + + + + + + + + + + + + + + Creates a new #WebKitContextMenu object to be used as a submenu of an existing +#WebKitContextMenu. The context menu of a #WebKitWebView is created by the view +and passed as an argument of #WebKitWebView::context-menu signal. +To add items to the menu use webkit_context_menu_prepend(), +webkit_context_menu_append() or webkit_context_menu_insert(). +See also webkit_context_menu_new_with_items() to create a #WebKitContextMenu with +a list of initial items. + + + The newly created #WebKitContextMenu object + + + + + Creates a new #WebKitContextMenu object to be used as a submenu of an existing +#WebKitContextMenu with the given initial items. +See also webkit_context_menu_new() + + + The newly created #WebKitContextMenu object + + + + + a #GList of #WebKitContextMenuItem + + + + + + + + Adds @item at the end of the @menu. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to add + + + + + + Gets the first item in the @menu. + + + the first #WebKitContextMenuItem of @menu, + or %NULL if the #WebKitContextMenu is empty. + + + + + a #WebKitContextMenu + + + + + + Gets the item at the given position in the @menu. + + + the #WebKitContextMenuItem at position @position in @menu, + or %NULL if the position is off the end of the @menu. + + + + + a #WebKitContextMenu + + + + the position of the item, counting from 0 + + + + + + Returns the item list of @menu. + + + a #GList of + #WebKitContextMenuItem<!-- -->s + + + + + + + a #WebKitContextMenu + + + + + + Gets the length of the @menu. + + + the number of #WebKitContextMenuItem<!-- -->s in @menu + + + + + a #WebKitContextMenu + + + + + + Gets the user data of @menu. +This function can be used from the UI Process to get user data previously set +from the Web Process with webkit_context_menu_set_user_data(). + + + the user data of @menu, or %NULL if @menu doesn't have user data + + + + + a #WebKitContextMenu + + + + + + Inserts @item into the @menu at the given position. +If @position is negative, or is larger than the number of items +in the #WebKitContextMenu, the item is added on to the end of +the @menu. The first position is 0. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to add + + + + the position to insert the item + + + + + + Gets the last item in the @menu. + + + the last #WebKitContextMenuItem of @menu, + or %NULL if the #WebKitContextMenu is empty. + + + + + a #WebKitContextMenu + + + + + + Moves @item to the given position in the @menu. +If @position is negative, or is larger than the number of items +in the #WebKitContextMenu, the item is added on to the end of +the @menu. +The first position is 0. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to add + + + + the new position to move the item + + + + + + Adds @item at the beginning of the @menu. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to add + + + + + + Removes @item from the @menu. +See also webkit_context_menu_remove_all() to remove all items. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to remove + + + + + + Removes all items of the @menu. + + + + + + + a #WebKitContextMenu + + + + + + Sets user data to @menu. +This function can be used from a Web Process extension to set user data +that can be retrieved from the UI Process using webkit_context_menu_get_user_data(). +If the @user_data #GVariant is floating, it is consumed. + + + + + + + a #WebKitContextMenu + + + + a #GVariant + + + + + + + + + + + + + Enum values used to denote the stock actions for +#WebKitContextMenuItem<!-- -->s + + No action, used by separator menu items. + + + Open current link. + + + Open current link in a new window. + + + Download link destination. + + + Copy link location to the clipboard. + + + Open current image in a new window. + + + Download current image. + + + Copy current image to the clipboard. + + + Copy current image location to the clipboard. + + + Open current frame in a new window. + + + Load the previous history item. + + + Load the next history item. + + + Stop any ongoing loading operation. + + + Reload the contents of current view. + + + Copy current selection the clipboard. + + + Cut current selection to the clipboard. + + + Paste clipboard contents. + + + Delete current selection. + + + Select all text. + + + Input methods menu. + + + Unicode menu. + + + A proposed replacement for a misspelled word. + + + An indicator that spellchecking found no proposed replacements. + + + Causes the spellchecker to ignore the word for this session. + + + Causes the spellchecker to add the word to the dictionary. + + + Ignore grammar. + + + Font options menu. + + + Bold. + + + Italic. + + + Underline. + + + Outline. + + + Open current element in the inspector. + + + Open current video element in a new window. + + + Open current audio element in a new window. + + + Copy video link location in to the clipboard. + + + Copy audio link location in to the clipboard. + + + Enable or disable media controls. + + + Enable or disable media loop. + + + Show current video element in fullscreen mode. + + + Play current media element. + + + Pause current media element. + + + Mute current media element. + + + Download video to disk. Since 2.2 + + + Download audio to disk. Since 2.2 + + + Insert an emoji. Since 2.26 + + + Custom action defined by applications. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #WebKitContextMenuItem for the given @action. + Use webkit_context_menu_item_new_from_gaction() instead. + + + the newly created #WebKitContextMenuItem object. + + + + + a #GtkAction + + + + + + Creates a new #WebKitContextMenuItem for the given @action and @label. On activation +@target will be passed as parameter to the callback. + + + the newly created #WebKitContextMenuItem object. + + + + + a #GAction + + + + the menu item label text + + + + a #GVariant to use as the action target + + + + + + Creates a new #WebKitContextMenuItem for the given stock action. +Stock actions are handled automatically by WebKit so that, for example, +when a menu item created with a %WEBKIT_CONTEXT_MENU_ACTION_STOP is +activated the action associated will be handled by WebKit and the current +load operation will be stopped. You can get the #GtkAction of a +#WebKitContextMenuItem created with a #WebKitContextMenuAction with +webkit_context_menu_item_get_action() and connect to #GtkAction::activate signal +to be notified when the item is activated. But you can't prevent the associated +action from being performed. + + + the newly created #WebKitContextMenuItem object. + + + + + a #WebKitContextMenuAction stock action + + + + + + Creates a new #WebKitContextMenuItem for the given stock action using the given @label. +Stock actions have a predefined label, this method can be used to create a +#WebKitContextMenuItem for a #WebKitContextMenuAction but using a custom label. + + + the newly created #WebKitContextMenuItem object. + + + + + a #WebKitContextMenuAction stock action + + + + a custom label text to use instead of the predefined one + + + + + + Creates a new #WebKitContextMenuItem representing a separator. + + + the newly created #WebKitContextMenuItem object. + + + + + Creates a new #WebKitContextMenuItem using the given @label with a submenu. + + + the newly created #WebKitContextMenuItem object. + + + + + the menu item label text + + + + a #WebKitContextMenu to set + + + + + + Gets the action associated to @item as a #GtkAction. + Use webkit_context_menu_item_get_gaction() instead. + + + the #GtkAction associated to the #WebKitContextMenuItem, + or %NULL if @item is a separator. + + + + + a #WebKitContextMenuItem + + + + + + Gets the action associated to @item as a #GAction. + + + the #GAction associated to the #WebKitContextMenuItem, + or %NULL if @item is a separator. + + + + + a #WebKitContextMenuItem + + + + + + Gets the #WebKitContextMenuAction of @item. If the #WebKitContextMenuItem was not +created for a stock action %WEBKIT_CONTEXT_MENU_ACTION_CUSTOM will be +returned. If the #WebKitContextMenuItem is a separator %WEBKIT_CONTEXT_MENU_ACTION_NO_ACTION +will be returned. + + + the #WebKitContextMenuAction of @item + + + + + a #WebKitContextMenuItem + + + + + + Gets the submenu of @item. + + + the #WebKitContextMenu representing the submenu of + @item or %NULL if @item doesn't have a submenu. + + + + + a #WebKitContextMenuItem + + + + + + Checks whether @item is a separator. + + + %TRUE is @item is a separator or %FALSE otherwise + + + + + a #WebKitContextMenuItem + + + + + + Sets or replaces the @item submenu. If @submenu is %NULL the current +submenu of @item is removed. + + + + + + + a #WebKitContextMenuItem + + + + a #WebKitContextMenu + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote the cookie acceptance policies. + + Accept all cookies unconditionally. + + + Reject all cookies unconditionally. + + + Accept only cookies set by the main document loaded. + + + + + + Asynchronously add a #SoupCookie to the underlying storage. + +When the operation is finished, @callback will be called. You can then call +webkit_cookie_manager_add_cookie_finish() to get the result of the operation. + + + + + + + a #WebKitCookieManager + + + + the #SoupCookie to be added + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_cookie_manager_add_cookie(). + + + %TRUE if the cookie was added or %FALSE in case of error. + + + + + a #WebKitCookieManager + + + + a #GAsyncResult + + + + + + Delete all cookies of @cookie_manager + Use webkit_website_data_manager_clear() instead. + + + + + + + a #WebKitCookieManager + + + + + + Asynchronously delete a #SoupCookie from the current session. + +When the operation is finished, @callback will be called. You can then call +webkit_cookie_manager_delete_cookie_finish() to get the result of the operation. + + + + + + + a #WebKitCookieManager + + + + the #SoupCookie to be deleted + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_cookie_manager_delete_cookie(). + + + %TRUE if the cookie was deleted or %FALSE in case of error. + + + + + a #WebKitCookieManager + + + + a #GAsyncResult + + + + + + Remove all cookies of @cookie_manager for the given @domain. + Use webkit_website_data_manager_remove() instead. + + + + + + + a #WebKitCookieManager + + + + a domain name + + + + + + Asynchronously get the cookie acceptance policy of @cookie_manager. + +When the operation is finished, @callback will be called. You can then call +webkit_cookie_manager_get_accept_policy_finish() to get the result of the operation. + + + + + + + a #WebKitCookieManager + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_cookie_manager_get_accept_policy(). + + + the cookie acceptance policy of @cookie_manager as a #WebKitCookieAcceptPolicy. + + + + + a #WebKitCookieManager + + + + a #GAsyncResult + + + + + + Asynchronously get a list of #SoupCookie from @cookie_manager associated with @uri, which +must be either an HTTP or an HTTPS URL. + +When the operation is finished, @callback will be called. You can then call +webkit_cookie_manager_get_cookies_finish() to get the result of the operation. + + + + + + + a #WebKitCookieManager + + + + the URI associated to the cookies to be retrieved + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_cookie_manager_get_cookies(). +The return value is a #GSList of #SoupCookie instances which should be released +with g_list_free_full() and soup_cookie_free(). + + + A #GList of #SoupCookie instances. + + + + + + + a #WebKitCookieManager + + + + a #GAsyncResult + + + + + + Asynchronously get the list of domains for which @cookie_manager contains cookies. + +When the operation is finished, @callback will be called. You can then call +webkit_cookie_manager_get_domains_with_cookies_finish() to get the result of the operation. + Use webkit_website_data_manager_fetch() instead. + + + + + + + a #WebKitCookieManager + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_cookie_manager_get_domains_with_cookies(). +The return value is a %NULL terminated list of strings which should +be released with g_strfreev(). + Use webkit_website_data_manager_fetch_finish() instead. + + + A %NULL terminated array of domain names + or %NULL in case of error. + + + + + + + a #WebKitCookieManager + + + + a #GAsyncResult + + + + + + Set the cookie acceptance policy of @cookie_manager as @policy. + + + + + + + a #WebKitCookieManager + + + + a #WebKitCookieAcceptPolicy + + + + + + Set the @filename where non-session cookies are stored persistently using +@storage as the format to read/write the cookies. +Cookies are initially read from @filename to create an initial set of cookies. +Then, non-session cookies will be written to @filename when the WebKitCookieManager::changed +signal is emitted. +By default, @cookie_manager doesn't store the cookies persistently, so you need to call this +method to keep cookies saved across sessions. + +This method should never be called on a #WebKitCookieManager associated to an ephemeral #WebKitWebsiteDataManager. + + + + + + + a #WebKitCookieManager + + + + the filename to read to/write from + + + + a #WebKitCookiePersistentStorage + + + + + + + + + + + + This signal is emitted when cookies are added, removed or modified. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote the cookie persistent storage types. + + Cookies are stored in a text + file in the Mozilla "cookies.txt" format. + + + Cookies are stored in a SQLite + file in the current Mozilla format. + + + + + + Create a new credential from the provided username, password and persistence mode. + + + A #WebKitCredential. + + + + + The username for the new credential + + + + The password for the new credential + + + + The #WebKitCredentialPersistence of the new credential + + + + + + Make a copy of the #WebKitCredential. + + + A copy of passed in #WebKitCredential + + + + + a #WebKitCredential + + + + + + Free the #WebKitCredential. + + + + + + + A #WebKitCredential + + + + + + Get the password currently held by this #WebKitCredential. + + + The password stored in the #WebKitCredential. + + + + + a #WebKitCredential + + + + + + Get the persistence mode currently held by this #WebKitCredential. + + + The #WebKitCredentialPersistence stored in the #WebKitCredential. + + + + + a #WebKitCredential + + + + + + Get the username currently held by this #WebKitCredential. + + + The username stored in the #WebKitCredential. + + + + + a #WebKitCredential + + + + + + Determine whether this credential has a password stored. + + + %TRUE if the credential has a password or %FALSE otherwise. + + + + + a #WebKitCredential + + + + + + + Enum values representing the duration for which a credential persists. + + Credential does not persist + + + Credential persists for session only + + + Credential persists permanently + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Cancels the download. When the ongoing download +operation is effectively cancelled the signal +#WebKitDownload::failed is emitted with +%WEBKIT_DOWNLOAD_ERROR_CANCELLED_BY_USER error. + + + + + + + a #WebKitDownload + + + + + + Returns the current value of the #WebKitDownload:allow-overwrite property, +which determines whether the download will overwrite an existing file on +disk, or if it will fail if the destination already exists. + + + the current value of the #WebKitDownload:allow-overwrite property + + + + + a #WebKitDownload + + + + + + Obtains the URI to which the downloaded file will be written. You +can connect to #WebKitDownload::created-destination to make +sure this method returns a valid destination. + + + the destination URI or %NULL + + + + + a #WebKitDownload + + + + + + Gets the elapsed time in seconds, including any fractional part. +If the download finished, had an error or was cancelled this is +the time between its start and the event. + + + seconds since the download was started + + + + + a #WebKitDownload + + + + + + Gets the value of the #WebKitDownload:estimated-progress property. +You can monitor the estimated progress of the download operation by +connecting to the notify::estimated-progress signal of @download. + + + an estimate of the of the percent complete for a download + as a range from 0.0 to 1.0. + + + + + a #WebKitDownload + + + + + + Gets the length of the data already downloaded for @download +in bytes. + + + the amount of bytes already downloaded. + + + + + a #WebKitDownload + + + + + + Retrieves the #WebKitURIRequest object that backs the download +process. + + + the #WebKitURIRequest of @download + + + + + a #WebKitDownload + + + + + + Retrieves the #WebKitURIResponse object that backs the download +process. This method returns %NULL if called before the response +is received from the server. You can connect to notify::response +signal to be notified when the response is received. + + + the #WebKitURIResponse, or %NULL if + the response hasn't been received yet. + + + + + a #WebKitDownload + + + + + + Get the #WebKitWebView that initiated the download. + + + the #WebKitWebView that initiated @download, + or %NULL if @download was not initiated by a #WebKitWebView. + + + + + a #WebKitDownload + + + + + + Sets the #WebKitDownload:allow-overwrite property, which determines whether +the download may overwrite an existing file on disk, or if it will fail if +the destination already exists. + + + + + + + a #WebKitDownload + + + + the new value for the #WebKitDownload:allow-overwrite property + + + + + + Sets the URI to which the downloaded file will be written. +This method should be called before the download transfer +starts or it will not have any effect on the ongoing download +operation. To set the destination using the filename suggested +by the server connect to #WebKitDownload::decide-destination +signal and call webkit_download_set_destination(). If you want to +set a fixed destination URI that doesn't depend on the suggested +filename you can connect to notify::response signal and call +webkit_download_set_destination(). +If #WebKitDownload::decide-destination signal is not handled +and destination URI is not set when the download transfer starts, +the file will be saved with the filename suggested by the server in +%G_USER_DIRECTORY_DOWNLOAD directory. + + + + + + + a #WebKitDownload + + + + the destination URI + + + + + + Whether or not the download is allowed to overwrite an existing file on +disk. If this property is %FALSE and the destination already exists, +the download will fail. + + + + The local URI to where the download will be saved. + + + + An estimate of the percent completion for the download operation. +This value will range from 0.0 to 1.0. The value is an estimate +based on the total number of bytes expected to be received for +a download. +If you need a more accurate progress information you can connect to +#WebKitDownload::received-data signal to track the progress. + + + + The #WebKitURIResponse associated with this download. + + + + + + + + + + This signal is emitted after #WebKitDownload::decide-destination and before +#WebKitDownload::received-data to notify that destination file has been +created successfully at @destination. + + + + + + the destination URI + + + + + + This signal is emitted after response is received to +decide a destination URI for the download. If this signal is not +handled the file will be downloaded to %G_USER_DIRECTORY_DOWNLOAD +directory using @suggested_filename. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the filename suggested for the download + + + + + + This signal is emitted when an error occurs during the download +operation. The given @error, of the domain %WEBKIT_DOWNLOAD_ERROR, +contains further details of the failure. If the download is cancelled +with webkit_download_cancel(), this signal is emitted with error +%WEBKIT_DOWNLOAD_ERROR_CANCELLED_BY_USER. The download operation finishes +after an error and #WebKitDownload::finished signal is emitted after this one. + + + + + + the #GError that was triggered + + + + + + This signal is emitted when download finishes successfully or due to an error. +In case of errors #WebKitDownload::failed signal is emitted before this one. + + + + + + This signal is emitted after response is received, +every time new data has been written to the destination. It's +useful to know the progress of the download operation. + + + + + + the length of data received in bytes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote the various download errors. + + Download failure due to network error + + + Download was cancelled by user + + + Download failure due to destination error + + + + + + + + + + + + The copy clipboard command. Copies the current selection inside +a #WebKitWebView to the clipboard. +You can check whether it's possible to execute the command with +webkit_web_view_can_execute_editing_command(). In general it's +possible to copy to the clipboard when there is an active selection +inside the #WebKitWebView. + + + + + The create link command. Creates a link element that is inserted at +the current cursor position. If there's a selection, the selected text +will be used as the link text, otherwise the URL itself will be used. +It receives the link URL as argument. This command should be executed +with webkit_web_view_execute_editing_command_with_argument() + + + + + The cut clipboard command. Copies the current selection inside +a #WebKitWebView to the clipboard and deletes the selected content. +You can check whether it's possible to execute the command with +webkit_web_view_can_execute_editing_command(). In general it's +possible to cut to the clipboard when the #WebKitWebView content is +editable and there is an active selection. + + + + + The insert image command. Creates an image element that is inserted at +the current cursor position. It receives an URI as argument, +that is used as the image source. This command should be executed with +webkit_web_view_execute_editing_command_with_argument(). + + + + + The paste clipboard command. Pastes the contents of the clipboard to +a #WebKitWebView. +You can check whether it's possible to execute the command with +webkit_web_view_can_execute_editing_command(). In general it's possible +to paste from the clipboard when the #WebKitWebView content is editable +and clipboard is not empty. + + + + + The redo command. Redoes a previously undone editing command in +a #WebKitWebView. +You can check whether it's possible to execute the command with +webkit_web_view_can_execute_editing_command(). It's only possible +to redo a command when it has been previously undone. + + + + + The select all command. Selects all the content of the current text field in +a #WebKitWebView. +It is always possible to select all text, no matter whether the +#WebKitWebView content is editable or not. You can still check it +with webkit_web_view_can_execute_editing_command(). + + + + + The undo command. Undoes the last editing command in a #WebKitWebView. +You can check whether it's possible to execute the command with +webkit_web_view_can_execute_editing_command(). It's only possible +to undo a command after a previously executed editing operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gets the typing attributes at the current cursor position. +If there is a selection, this returns the typing attributes +of the selected text. Note that in case of a selection, +typing attributes are considered active only when they are +present throughout the selection. + + + a bitmask of #WebKitEditorTypingAttributes flags + + + + + a #WebKitEditorState + + + + + + Gets whether a copy command can be issued. + + + %TRUE if copy is currently available + + + + + a #WebKitEditorState + + + + + + Gets whether a cut command can be issued. + + + %TRUE if cut is currently available + + + + + a #WebKitEditorState + + + + + + Gets whether a paste command can be issued. + + + %TRUE if paste is currently available + + + + + a #WebKitEditorState + + + + + + Gets whether a redo command can be issued. + + + %TRUE if redo is currently available + + + + + a #WebKitEditorState + + + + + + Gets whether an undo command can be issued. + + + %TRUE if undo is currently available + + + + + a #WebKitEditorState + + + + + + Bitmask of #WebKitEditorTypingAttributes flags. +See webkit_editor_state_get_typing_attributes() for more information. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values with flags representing typing attributes. + + No typing attributes. + + + Bold typing attribute. + + + Italic typing attribute. + + + Underline typing attribute. + + + Strikethrough typing attribute. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Clears all icons from the database. + + + + + + + a #WebKitFaviconDatabase + + + + + + Asynchronously obtains a #cairo_surface_t of the favicon for the +given page URI. It returns the cached icon if it's in the database +asynchronously waiting for the icon to be read from the database. + +This is an asynchronous method. When the operation is finished, callback will +be invoked. You can then call webkit_favicon_database_get_favicon_finish() +to get the result of the operation. + +You must call webkit_web_context_set_favicon_database_directory() for +the #WebKitWebContext associated with this #WebKitFaviconDatabase +before attempting to use this function; otherwise, +webkit_favicon_database_get_favicon_finish() will return +%WEBKIT_FAVICON_DATABASE_ERROR_NOT_INITIALIZED. + + + + + + + a #WebKitFaviconDatabase + + + + URI of the page for which we want to retrieve the favicon + + + + 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 webkit_favicon_database_get_favicon(). + + + a new reference to a #cairo_surface_t, or +%NULL in case of error. + + + + + a #WebKitFaviconDatabase + + + + A #GAsyncResult obtained from the #GAsyncReadyCallback passed to webkit_favicon_database_get_favicon() + + + + + + Obtains the URI of the favicon for the given @page_uri. + + + a newly allocated URI for the favicon, or %NULL if the +database doesn't have a favicon for @page_uri. + + + + + a #WebKitFaviconDatabase + + + + URI of the page containing the icon + + + + + + + + + + + + This signal is emitted when the favicon URI of @page_uri has +been changed to @favicon_uri in the database. You can connect +to this signal and call webkit_favicon_database_get_favicon() +to get the favicon. If you are interested in the favicon of a +#WebKitWebView it's easier to use the #WebKitWebView:favicon +property. See webkit_web_view_get_favicon() for more details. + + + + + + the URI of the Web page containing the icon + + + + the URI of the favicon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote the various errors related to the #WebKitFaviconDatabase. + + The #WebKitFaviconDatabase has not been initialized yet + + + There is not an icon available for the requested URL + + + There might be an icon for the requested URL, but its data is unknown at the moment + + + + + + + + + + + + + + Ask WebKit to cancel the request. It's important to do this in case +no selection has been made in the client, otherwise the request +won't be properly completed and the browser will keep the request +pending forever, which might cause the browser to hang. + + + + + + + a #WebKitFileChooserRequest + + + + + + Get the list of MIME types the file chooser dialog should handle, +in the format specified in RFC 2046 for "media types". Its contents +depend on the value of the 'accept' attribute for HTML input +elements. This function should normally be called before presenting +the file chooser dialog to the user, to decide whether to allow the +user to select multiple files at once or only one. + + + a +%NULL-terminated array of strings if a list of accepted MIME types +is defined or %NULL otherwise, meaning that any MIME type should be +accepted. This array and its contents are owned by WebKit and +should not be modified or freed. + + + + + + + a #WebKitFileChooserRequest + + + + + + Get the filter currently associated with the request, ready to be +used by #GtkFileChooser. This function should normally be called +before presenting the file chooser dialog to the user, to decide +whether to apply a filter so the user would not be allowed to +select files with other MIME types. + +See webkit_file_chooser_request_get_mime_types() if you are +interested in getting the list of accepted MIME types. + + + a #GtkFileFilter if a list of accepted +MIME types is defined or %NULL otherwise. The returned object is +owned by WebKit should not be modified or freed. + + + + + a #WebKitFileChooserRequest + + + + + + Determine whether the file chooser associated to this +#WebKitFileChooserRequest should allow selecting multiple files, +which depends on the HTML input element having a 'multiple' +attribute defined. + + + %TRUE if the file chooser should allow selecting multiple files or %FALSE otherwise. + + + + + a #WebKitFileChooserRequest + + + + + + Get the list of selected files currently associated to the +request. Initially, the return value of this method contains any +files selected in previous file chooser requests for this HTML +input element. Once webkit_file_chooser_request_select_files, the +value will reflect whatever files are given. + +This function should normally be called only before presenting the +file chooser dialog to the user, to decide whether to perform some +extra action, like pre-selecting the files from a previous request. + + + a +%NULL-terminated array of strings if there are selected files +associated with the request or %NULL otherwise. This array and its +contents are owned by WebKit and should not be modified or +freed. + + + + + + + a #WebKitFileChooserRequest + + + + + + Ask WebKit to select local files for upload and complete the +request. + + + + + + + a #WebKitFileChooserRequest + + + + a +%NULL-terminated array of strings, containing paths to local files. + + + + + + + + The filter currently associated with the request. See +webkit_file_chooser_request_get_mime_types_filter() for more +details. + + + + A %NULL-terminated array of strings containing the list of MIME +types the file chooser dialog should handle. See +webkit_file_chooser_request_get_mime_types() for more details. + + + + + + Whether the file chooser should allow selecting multiple +files. See +webkit_file_chooser_request_get_select_multiple() for +more details. + + + + A %NULL-terminated array of strings containing the list of +selected files associated to the current request. See +webkit_file_chooser_request_get_selected_files() for more details. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Counts the number of matches for @search_text found in the +#WebKitWebView with the provided @find_options. The number of +matches will be provided by the +#WebKitFindController::counted-matches signal. + + + + + + + the #WebKitFindController + + + + the text to look for + + + + a bitmask with the #WebKitFindOptions used in the search + + + + the maximum number of matches allowed in the search + + + + + + Gets the maximum number of matches to report during a text +lookup. This number is passed as the last argument of +webkit_find_controller_search() or +webkit_find_controller_count_matches(). + + + the maximum number of matches to report. + + + + + the #WebKitFindController + + + + + + Gets a bitmask containing the #WebKitFindOptions associated with +the current search. + + + a bitmask containing the #WebKitFindOptions associated +with the current search. + + + + + the #WebKitFindController + + + + + + Gets the text that @find_controller is currently searching +for. This text is passed to either +webkit_find_controller_search() or +webkit_find_controller_count_matches(). + + + the text to look for in the #WebKitWebView. + + + + + the #WebKitFindController + + + + + + Gets the #WebKitWebView this find controller is associated to. Do +not dereference the returned instance as it belongs to the +#WebKitFindController. + + + the #WebKitWebView. + + + + + the #WebKitFindController + + + + + + Looks for @search_text in the #WebKitWebView associated with +@find_controller since the beginning of the document highlighting +up to @max_match_count matches. The outcome of the search will be +asynchronously provided by the #WebKitFindController::found-text +and #WebKitFindController::failed-to-find-text signals. + +To look for the next or previous occurrences of the same text +with the same find options use webkit_find_controller_search_next() +and/or webkit_find_controller_search_previous(). The +#WebKitFindController will use the same text and options for the +following searches unless they are modified by another call to this +method. + +Note that if the number of matches is higher than @max_match_count +then #WebKitFindController::found-text will report %G_MAXUINT matches +instead of the actual number. + +Callers should call webkit_find_controller_search_finish() to +finish the current search operation. + + + + + + + the #WebKitFindController + + + + the text to look for + + + + a bitmask with the #WebKitFindOptions used in the search + + + + the maximum number of matches allowed in the search + + + + + + Finishes a find operation started by +webkit_find_controller_search(). It will basically unhighlight +every text match found. + +This method will be typically called when the search UI is +closed/hidden by the client application. + + + + + + + a #WebKitFindController + + + + + + Looks for the next occurrence of the search text. + +Calling this method before webkit_find_controller_search() or +webkit_find_controller_count_matches() is a programming error. + + + + + + + the #WebKitFindController + + + + + + Looks for the previous occurrence of the search text. + +Calling this method before webkit_find_controller_search() or +webkit_find_controller_count_matches() is a programming error. + + + + + + + the #WebKitFindController + + + + + + The maximum number of matches to report for a given search. + + + + The options to be used in the search operation. + + + + The current search text for this #WebKitFindController. + + + + The #WebKitWebView this controller is associated to. + + + + + + + + + + This signal is emitted when the #WebKitFindController has +counted the number of matches for a given text after a call +to webkit_find_controller_count_matches(). + + + + + + the number of matches of the search text + + + + + + This signal is emitted when a search operation does not find +any result for the given text. It will be issued if the text +is not found asynchronously after a call to +webkit_find_controller_search(), webkit_find_controller_search_next() +or webkit_find_controller_search_previous(). + + + + + + This signal is emitted when a given text is found in the web +page text. It will be issued if the text is found +asynchronously after a call to webkit_find_controller_search(), +webkit_find_controller_search_next() or +webkit_find_controller_search_previous(). + + + + + + the number of matches found of the search text + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to specify search options. + + no search flags, this means a case + sensitive, no wrap, forward only search. + + + case insensitive search. + + + search text only at the + begining of the words. + + + treat + capital letters in the middle of words as word start. + + + search backwards. + + + if not present search will stop + at the end of the document. + + + + + + Get a #GHashTable with the values of the text fields contained in the form +associated to @request. Note that fields will be missing if the form +contains multiple text input elements with the same name, so this +function does not reliably return all text fields. + Use webkit_form_submission_request_list_text_fields() instead. + + + a #GHashTable with the form + text fields, or %NULL if the form doesn't contain text fields. + + + + + + + + a #WebKitFormSubmissionRequest + + + + + + Get lists with the names and values of the text fields contained in +the form associated to @request. Note that names and values may be +%NULL. + +If this function returns %FALSE, then both @field_names and +@field_values will be empty. + + + %TRUE if the form contains text fields, or %FALSE otherwise + + + + + a #WebKitFormSubmissionRequest + + + + + names of the text fields in the form + + + + + + + values of the text fields in the form + + + + + + + + Continue the form submission. + + + + + + + a #WebKitFormSubmissionRequest + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Notify @manager that determining the position failed. + + + + + + + a #WebKitGeolocationManager + + + + the error message + + + + + + Get whether high accuracy is enabled. + + + + + + + a #WebKitGeolocationManager + + + + + + Notify @manager that position has been updated to @position. + + + + + + + a #WebKitGeolocationManager + + + + a #WebKitGeolocationPosition + + + + + + Whether high accuracy is enabled. This is a read-only property that will be +set to %TRUE when a #WebKitGeolocationManager needs to get accurate position updates. +You can connect to notify::enable-high-accuracy signal to monitor it. + + + + + + + + + + The signal is emitted to notify that @manager needs to start receiving +position updates. After this signal is emitted the user should provide +the updates using webkit_geolocation_manager_update_position() every time +the position changes, or use webkit_geolocation_manager_failed() in case +it isn't possible to determine the current position. + +If the signal is not handled, WebKit will try to determine the position +using GeoClue if available. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + The signal is emitted to notify that @manager doesn't need to receive +position updates anymore. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + WebKitGeolocationPosition is an opaque struct used to provide position updates to a +#WebKitGeolocationManager using webkit_geolocation_manager_update_position(). + + + Create a new #WebKitGeolocationPosition + + + a newly created #WebKitGeolocationPosition + + + + + a valid latitude in degrees + + + + a valid longitude in degrees + + + + accuracy of location in meters + + + + + + Make a copy of the #WebKitGeolocationPosition + + + a copy of @position + + + + + a #WebKitGeolocationPosition + + + + + + Free the #WebKitGeolocationPosition + + + + + + + a #WebKitGeolocationPosition + + + + + + Set the @position altitude + + + + + + + a #WebKitGeolocationPosition + + + + altitude in meters + + + + + + Set the accuracy of @position altitude + + + + + + + a #WebKitGeolocationPosition + + + + accuracy of position altitude in meters + + + + + + Set the @position heading, as a positive angle between the direction of movement and the North +direction, in clockwise direction. + + + + + + + a #WebKitGeolocationPosition + + + + heading in degrees + + + + + + Set the @position speed + + + + + + + a #WebKitGeolocationPosition + + + + speed in meters per second + + + + + + Set the @position timestamp. By default it's the time when the @position was created. + + + + + + + a #WebKitGeolocationPosition + + + + timestamp in seconds since the epoch, or 0 to use current time + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used for determining the hardware acceleration policy. + + Hardware acceleration is enabled/disabled as request by web contents. + + + Hardware acceleration is always enabled, even for websites not requesting it. + + + Hardware acceleration is always disabled, even for websites requesting it. + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_EDITABLE flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's an editable element at the coordinates of the @hit_test_result, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_IMAGE flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's an image element in the coordinates of the Hit Test, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_LINK flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's a link element in the coordinates of the Hit Test, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_MEDIA flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's a media element in the coordinates of the Hit Test, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_SCROLLBAR flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's a scrollbar element at the coordinates of the @hit_test_result, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_SELECTION flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's a selected element at the coordinates of the @hit_test_result, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:context property. + + + a bitmask of #WebKitHitTestResultContext flags + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:image-uri property. + + + the URI of the image element in the coordinates of the Hit Test, + or %NULL if there isn't an image element in @hit_test_result context + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:link-label property. + + + the label of the link element in the coordinates of the Hit Test, + or %NULL if there isn't a link element in @hit_test_result context or the + link element doesn't have a label + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:link-title property. + + + the title of the link element in the coordinates of the Hit Test, + or %NULL if there isn't a link element in @hit_test_result context or the + link element doesn't have a title + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:link-uri property. + + + the URI of the link element in the coordinates of the Hit Test, + or %NULL if there isn't a link element in @hit_test_result context + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:media-uri property. + + + the URI of the media element in the coordinates of the Hit Test, + or %NULL if there isn't a media element in @hit_test_result context + + + + + a #WebKitHitTestResult + + + + + + Bitmask of #WebKitHitTestResultContext flags representing +the context of the #WebKitHitTestResult. + + + + The URI of the image if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_IMAGE +is present in #WebKitHitTestResult:context + + + + The label of the link if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_LINK +is present in #WebKitHitTestResult:context + + + + The title of the link if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_LINK +is present in #WebKitHitTestResult:context + + + + The URI of the link if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_LINK +is present in #WebKitHitTestResult:context + + + + The URI of the media if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_MEDIA +is present in #WebKitHitTestResult:context + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values with flags representing the context of a #WebKitHitTestResult. + + anywhere in the document. + + + a hyperlink element. + + + an image element. + + + a video or audio element. + + + an editable element + + + a scrollbar element. + + + a selected element. Since 2.8 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote the different events which can trigger +the detection of insecure content. + + Insecure content has been detected by +trying to execute any kind of logic (e.g. a script) from an +untrusted source. + + + Insecure content has been +detected by trying to display any kind of resource (e.g. an image) +from an untrusted source. + + + + + + + Gets the description about the missing plugins provided by the media backend when a media couldn't be played. + + + a string with the description provided by the media backend. + + + + + a #WebKitInstallMissingMediaPluginsPermissionRequest + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote errors happening when executing JavaScript + + An exception was raised in JavaScript execution + + + + + + + + + + + Get the global Javascript context that should be used with the +<function>JSValueRef</function> returned by webkit_javascript_result_get_value(). + Use jsc_value_get_context() instead. + + + the <function>JSGlobalContextRef</function> for the #WebKitJavascriptResult + + + + + a #WebKitJavascriptResult + + + + + + Get the #JSCValue of @js_result. + + + the #JSCValue of the #WebKitJavascriptResult + + + + + a #WebKitJavascriptResult + + + + + + Get the value of @js_result. You should use the <function>JSGlobalContextRef</function> +returned by webkit_javascript_result_get_global_context() to use the <function>JSValueRef</function>. + Use webkit_javascript_result_get_js_value() instead. + + + the <function>JSValueRef</function> of the #WebKitJavascriptResult + + + + + a #WebKitJavascriptResult + + + + + + Atomically increments the reference count of @js_result by one. This +function is MT-safe and may be called from any thread. + + + The passed in #WebKitJavascriptResult + + + + + a #WebKitJavascriptResult + + + + + + Atomically decrements the reference count of @js_result by one. If the +reference count drops to 0, all memory allocated by the #WebKitJavascriptResult is +released. This function is MT-safe and may be called from any +thread. + + + + + + + a #WebKitJavascriptResult + + + + + + + Enum values used to denote the different events that happen during a +#WebKitWebView load operation. + + A new load request has been made. +No data has been received yet, empty structures have +been allocated to perform the load; the load may still +fail due to transport issues such as not being able to +resolve a name, or connect to a port. + + + A provisional data source received +a server redirect. + + + The content started arriving for a page load. +The necessary transport requirements are established, and the +load is being performed. + + + Load completed. All resources are done loading +or there was an error during the load operation. + + + + Like webkit_get_major_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + Like webkit_get_micro_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + Like webkit_get_minor_version(), but from the headers used at +application compile time, rather than from the library linked +against at application run time. + + + + + + + + + the description of the MIME type of @info + + + + + a #WebKitMimeInfo + + + + + + Get the list of file extensions associated to the +MIME type of @info + + + a + %NULL-terminated array of strings + + + + + + + a #WebKitMimeInfo + + + + + + + + the MIME type of @info + + + + + a #WebKitMimeInfo + + + + + + Atomically increments the reference count of @info by one. This +function is MT-safe and may be called from any thread. + + + The passed in #WebKitMimeInfo + + + + + a #WebKitMimeInfo + + + + + + Atomically decrements the reference count of @info by one. If the +reference count drops to 0, all memory allocated by the #WebKitMimeInfo is +released. This function is MT-safe and may be called from any +thread. + + + + + + + a #WebKitMimeInfo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Make a copy of @navigation. + + + A copy of passed in #WebKitNavigationAction + + + + + a #WebKitNavigationAction + + + + + + Free the #WebKitNavigationAction + + + + + + + a #WebKitNavigationAction + + + + + + Return a bitmask of #GdkModifierType values describing the modifier keys that were in effect +when the navigation was requested + + + the modifier keys + + + + + a #WebKitNavigationAction + + + + + + Return the number of the mouse button that triggered the navigation, or 0 if +the navigation was not started by a mouse event. + + + the mouse button number or 0 + + + + + a #WebKitNavigationAction + + + + + + Return the type of action that triggered the navigation. + + + a #WebKitNavigationType + + + + + a #WebKitNavigationAction + + + + + + Return the #WebKitURIRequest associated with the navigation action. +Modifications to the returned object are <emphasis>not</emphasis> taken +into account when the request is sent over the network, and is intended +only to aid in evaluating whether a navigation action should be taken or +not. To modify requests before they are sent over the network the +#WebKitPage::send-request signal can be used instead. + + + a #WebKitURIRequest + + + + + a #WebKitNavigationAction + + + + + + Returns whether the @navigation was redirected. + + + %TRUE if the original navigation was redirected, %FALSE otherwise. + + + + + a #WebKitNavigationAction + + + + + + Return whether the navigation was triggered by a user gesture like a mouse click. + + + whether navigation action is a user gesture + + + + + a #WebKitNavigationAction + + + + + + + + + Gets the value of the #WebKitNavigationPolicyDecision:frame-name property. + + + The name of the new frame this navigation action targets or %NULL + + + + + a #WebKitNavigationPolicyDecision + + + + + + Gets the value of the #WebKitNavigationPolicyDecision:modifiers property. + Use webkit_navigation_policy_decision_get_navigation_action() instead. + + + The modifiers active if this decision was triggered by a mouse event + + + + + a #WebKitNavigationPolicyDecision + + + + + + Gets the value of the #WebKitNavigationPolicyDecision:mouse-button property. + Use webkit_navigation_policy_decision_get_navigation_action() instead. + + + The mouse button used if this decision was triggered by a mouse event or 0 otherwise + + + + + a #WebKitNavigationPolicyDecision + + + + + + Gets the value of the #WebKitNavigationPolicyDecision:navigation-action property. + + + The #WebKitNavigationAction triggering this policy decision. + + + + + a #WebKitNavigationPolicyDecision + + + + + + Gets the value of the #WebKitNavigationPolicyDecision:navigation-type property. + Use webkit_navigation_policy_decision_get_navigation_action() instead. + + + The type of navigation triggering this policy decision. + + + + + a #WebKitNavigationPolicyDecision + + + + + + Gets the value of the #WebKitNavigationPolicyDecision:request property. + Use webkit_navigation_policy_decision_get_navigation_action() instead. + + + The URI request that is associated with this navigation + + + + + a #WebKitNavigationPolicyDecision + + + + + + If this navigation request targets a new frame, this property contains +the name of that frame. For example if the decision was triggered by clicking a +link with a target attribute equal to "_blank", this property will contain the +value of that attribute. In all other cases, this value will be %NULL. + + + + If the navigation associated with this policy decision was originally +triggered by a mouse event, this property contains a bitmask of various +#GdkModifierType values describing the modifiers used for that click. +If the navigation was not triggered by a mouse event or no modifiers +were active, the value of this property will be zero. + Use #WebKitNavigationPolicyDecision:navigation-action instead + + + + If the navigation associated with this policy decision was originally +triggered by a mouse event, this property contains non-zero button number +of the button triggering that event. The button numbers match those from GDK. +If the navigation was not triggered by a mouse event, the value of this +property will be 0. + Use #WebKitNavigationPolicyDecision:navigation-action instead + + + + The #WebKitNavigationAction that triggered this policy decision. + + + + The type of navigation that triggered this policy decision. This is +useful for enacting different policies depending on what type of user +action caused the navigation. + Use #WebKitNavigationPolicyDecision:navigation-action instead + + + + This property contains the #WebKitURIRequest associated with this +navigation. + Use #WebKitNavigationPolicyDecision:navigation-action instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote the various navigation types. + + The navigation was triggered by clicking a link. + + + The navigation was triggered by submitting a form. + + + The navigation was triggered by navigating forward or backward. + + + The navigation was triggered by reloading. + + + The navigation was triggered by resubmitting a form. + + + The navigation was triggered by some other action. + + + + Enum values used to denote the various network errors. + + Generic load failure + + + Load failure due to transport error + + + Load failure due to unknown protocol + + + Load failure due to cancellation + + + Load failure due to missing file + + + + + + + + + Enum values used to set the network proxy mode. + + Use the default proxy of the system. + + + Do not use any proxy. + + + Use custom proxy settings. + + + + + + Create a new #WebKitNetworkProxySettings with the given @default_proxy_uri and @ignore_hosts. + +The default proxy URI will be used for any URI that doesn't match @ignore_hosts, and doesn't match any +of the schemes added with webkit_network_proxy_settings_add_proxy_for_scheme(). +If @default_proxy_uri starts with "socks://", it will be treated as referring to all three of the +socks5, socks4a, and socks4 proxy types. + +@ignore_hosts is a list of hostnames and IP addresses that the resolver should allow direct connections to. +Entries can be in one of 4 formats: +<itemizedlist> +<listitem><para> +A hostname, such as "example.com", ".example.com", or "*.example.com", any of which match "example.com" or +any subdomain of it. +</para></listitem> +<listitem><para> +An IPv4 or IPv6 address, such as "192.168.1.1", which matches only that address. +</para></listitem> +<listitem><para> +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" +</para></listitem> +<listitem><para> +An IP address range, given by a base address and prefix length, such as "fe80::/10", which matches any address in that range. +</para></listitem> +</itemizedlist> + +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 @ignore_hosts +contains only "192.168.1.1", then a connection to "example.com" will use the proxy, and a connection to 192.168.1.1" will not. + + + A new #WebKitNetworkProxySettings. + + + + + the default proxy URI to use, or %NULL. + + + + an optional list of hosts/IP addresses to not use a proxy for. + + + + + + + + Adds a URI-scheme-specific proxy. URIs whose scheme matches @uri_scheme will be proxied via @proxy_uri. +As with the default proxy URI, if @proxy_uri starts with "socks://", it will be treated as referring to +all three of the socks5, socks4a, and socks4 proxy types. + + + + + + + a #WebKitNetworkProxySettings + + + + the URI scheme to add a proxy for + + + + the proxy URI to use for @uri_scheme + + + + + + Make a copy of the #WebKitNetworkProxySettings. + + + A copy of passed in #WebKitNetworkProxySettings + + + + + a #WebKitNetworkProxySettings + + + + + + Free the #WebKitNetworkProxySettings. + + + + + + + A #WebKitNetworkProxySettings + + + + + + + + + Tells WebKit the notification has been clicked. This will emit the +#WebKitNotification::clicked signal. + + + + + + + a #WebKitNotification + + + + + + Closes the notification. + + + + + + + a #WebKitNotification + + + + + + Obtains the body for the notification. + + + the body for the notification + + + + + a #WebKitNotification + + + + + + Obtains the unique id for the notification. + + + the unique id for the notification + + + + + a #WebKitNotification + + + + + + Obtains the tag identifier for the notification. + + + the tag for the notification + + + + + a #WebKitNotification + + + + + + Obtains the title for the notification. + + + the title for the notification + + + + + a #WebKitNotification + + + + + + The body for the notification. + + + + The unique id for the notification. + + + + The tag identifier for the notification. + + + + The title for the notification. + + + + + + + + + + Emitted when a notification has been clicked. See webkit_notification_clicked(). + + + + + + Emitted when a notification has been withdrawn. + +The default handler will close the notification using libnotify, if built with +support for it. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Activates the #WebKitOptionMenuItem at @index in @menu. Activating an item changes the value +of the element making the item the active one. You are expected to close the menu with +webkit_option_menu_close() after activating an item, calling this function again will have no +effect. + + + + + + + a #WebKitOptionMenu + + + + the index of the item + + + + + + Request to close a #WebKitOptionMenu. This emits WebKitOptionMenu::close signal. +This function should always be called to notify WebKit that the associated +menu has been closed. If the menu is closed and neither webkit_option_menu_select_item() +nor webkit_option_menu_activate_item() have been called, the element value remains +unchanged. + + + + + + + a #WebKitOptionMenu + + + + + + Returns the #WebKitOptionMenuItem at @index in @menu. + + + a #WebKitOptionMenuItem of @menu. + + + + + a #WebKitOptionMenu + + + + the index of the item + + + + + + Gets the length of the @menu. + + + the number of #WebKitOptionMenuItem<!-- -->s in @menu + + + + + a #WebKitOptionMenu + + + + + + Selects the #WebKitOptionMenuItem at @index in @menu. Selecting an item changes the +text shown by the combo button, but it doesn't change the value of the element. You need to +explicitly activate the item with webkit_option_menu_select_item() or close the menu with +webkit_option_menu_close() in which case the currently selected item will be activated. + + + + + + + a #WebKitOptionMenu + + + + the index of the item + + + + + + + + + + + + Emitted when closing a #WebKitOptionMenu is requested. This can happen +when the user explicitly calls webkit_option_menu_close() or when the +element is detached from the current page. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Make a copy of the #WebKitOptionMenuItem. + + + A copy of passed in #WebKitOptionMenuItem + + + + + a #WebKitOptionMenuItem + + + + + + Free the #WebKitOptionMenuItem. + + + + + + + A #WebKitOptionMenuItem + + + + + + Get the label of a #WebKitOptionMenuItem. + + + The label of @item. + + + + + a #WebKitOptionMenuItem + + + + + + Get the tooltip of a #WebKitOptionMenuItem. + + + The tooltip of @item, or %NULL. + + + + + a #WebKitOptionMenuItem + + + + + + Whether a #WebKitOptionMenuItem is enabled. + + + %TRUE if the @item is enabled or %FALSE otherwise. + + + + + a #WebKitOptionMenuItem + + + + + + Whether a #WebKitOptionMenuItem is a group child. + + + %TRUE if the @item is a group child or %FALSE otherwise. + + + + + a #WebKitOptionMenuItem + + + + + + Whether a #WebKitOptionMenuItem is a group label. + + + %TRUE if the @item is a group label or %FALSE otherwise. + + + + + a #WebKitOptionMenuItem + + + + + + Whether a #WebKitOptionMenuItem is the currently selected one. + + + %TRUE if the @item is selected or %FALSE otherwise. + + + + + a #WebKitOptionMenuItem + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Allow the action which triggered this request. + + + + + + + a #WebKitPermissionRequest + + + + + + Deny the action which triggered this request. + + + + + + + a #WebKitPermissionRequest + + + + + + Allow the action which triggered this request. + + + + + + + a #WebKitPermissionRequest + + + + + + Deny the action which triggered this request. + + + + + + + a #WebKitPermissionRequest + + + + + + + + + + + + + + + + + + + a #WebKitPermissionRequest + + + + + + + + + + + + + + a #WebKitPermissionRequest + + + + + + + + + + + + the description of the plugin. + + + + + a #WebKitPlugin + + + + + + Get information about MIME types handled by the plugin, +as a list of #WebKitMimeInfo. + + + a #GList of #WebKitMimeInfo. + + + + + + + a #WebKitPlugin + + + + + + + + the name of the plugin. + + + + + a #WebKitPlugin + + + + + + + + the absolute path where the plugin is installed. + + + + + a #WebKitPlugin + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote the various plugin errors. + + Generic plugin load failure + + + Load failure due to missing plugin + + + Load failure due to inability to load plugin + + + Load failure due to missing Java support that is required to load plugin + + + Load failure due to connection cancellation + + + Load failure since plugin handles the load + + + + + + + + + + + + + + Spawn a download from this decision. + + + + + + + a #WebKitPolicyDecision + + + + + + Ignore the action which triggered this decision. For instance, for a +#WebKitResponsePolicyDecision, this would cancel the request. + + + + + + + a #WebKitPolicyDecision + + + + + + Accept the action which triggered this decision. + + + + + + + a #WebKitPolicyDecision + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used for determining the type of a policy decision during +#WebKitWebView::decide-policy. + + This type of policy decision + is requested when WebKit is about to navigate to a new page in either the + main frame or a subframe. Acceptable policy decisions are either + webkit_policy_decision_use() or webkit_policy_decision_ignore(). This + type of policy decision is always a #WebKitNavigationPolicyDecision. + + + This type of policy decision + is requested when WebKit is about to create a new window. Acceptable policy + decisions are either webkit_policy_decision_use() or + webkit_policy_decision_ignore(). This type of policy decision is always + a #WebKitNavigationPolicyDecision. These decisions are useful for implementing + special actions for new windows, such as forcing the new window to open + in a tab when a keyboard modifier is active or handling a special + target attribute on &lt;a&gt; elements. + + + This type of decision is used when WebKit has + received a response for a network resource and is about to start the load. + Note that these resources include all subresources of a page such as images + and stylesheets as well as main documents. Appropriate policy responses to + this decision are webkit_policy_decision_use(), webkit_policy_decision_ignore(), + or webkit_policy_decision_download(). This type of policy decision is always + a #WebKitResponsePolicyDecision. This decision is useful for forcing + some types of resources to be downloaded rather than rendered in the WebView + or to block the transfer of resources entirely. + + + + Enum values used to denote the various policy errors. + + Generic load failure due to policy error + + + Load failure due to unsupported mime type + + + Load failure due to URI that can not be shown + + + Load failure due to frame load interruption by policy change + + + Load failure due to port restriction + + + + + + + + + + + Create a new #WebKitPrintCustomWidget with given @widget and @title. The @widget +ownership is taken and it is destroyed together with the dialog even if this +object could still be alive at that point. You typically want to pass a container +widget with multiple widgets in it. + + + a new #WebKitPrintOperation. + + + + + a #GtkWidget + + + + a @widget's title + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Return the value of #WebKitPrintCustomWidget:title property for the given +@print_custom_widget object. + + + Title of the @print_custom_widget. + + + + + a #WebKitPrintCustomWidget + + + + + + Return the value of #WebKitPrintCustomWidget:widget property for the given +@print_custom_widget object. The returned value will always be valid if called +from #WebKitPrintCustomWidget::apply or #WebKitPrintCustomWidget::update +callbacks, but it will be %NULL if called after the +#WebKitPrintCustomWidget::apply signal is emitted. + + + a #GtkWidget. + + + + + a #WebKitPrintCustomWidget + + + + + + The title of the custom widget. + + + + The custom #GtkWidget that will be embedded in the dialog. + + + + + + + + + + Emitted right before the printing will start. You should read the information +from the widget and update the content based on it if necessary. The widget +is not guaranteed to be valid at a later time. + + + + + + Emitted after change of selected printer in the dialog. The actual page setup +and print settings are available and the custom widget can actualize itself +according to their values. + + + + + + actual page setup + + + + actual print settings + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote the various print errors. + + Unspecified error during a print operation + + + Selected printer cannot be found + + + Invalid page range + + + + + + + + + + + Create a new #WebKitPrintOperation to print @web_view contents. + + + a new #WebKitPrintOperation. + + + + + a #WebKitWebView + + + + + + Return the current page setup of @print_operation. It returns %NULL until +either webkit_print_operation_set_page_setup() or webkit_print_operation_run_dialog() +have been called. + + + the current #GtkPageSetup of @print_operation. + + + + + a #WebKitPrintOperation + + + + + + Return the current print settings of @print_operation. It returns %NULL until +either webkit_print_operation_set_print_settings() or webkit_print_operation_run_dialog() +have been called. + + + the current #GtkPrintSettings of @print_operation. + + + + + a #WebKitPrintOperation + + + + + + Start a print operation using current print settings and page setup +without showing the print dialog. If either print settings or page setup +are not set with webkit_print_operation_set_print_settings() and +webkit_print_operation_set_page_setup(), the default options will be used +and the print job will be sent to the default printer. +The #WebKitPrintOperation::finished signal is emitted when the printing +operation finishes. If an error occurs while printing the signal +#WebKitPrintOperation::failed is emitted before #WebKitPrintOperation::finished. + + + + + + + a #WebKitPrintOperation + + + + + + Run the print dialog and start printing using the options selected by +the user. This method returns when the print dialog is closed. +If the print dialog is cancelled %WEBKIT_PRINT_OPERATION_RESPONSE_CANCEL +is returned. If the user clicks on the print button, %WEBKIT_PRINT_OPERATION_RESPONSE_PRINT +is returned and the print operation starts. In this case, the #WebKitPrintOperation::finished +signal is emitted when the operation finishes. If an error occurs while printing, the signal +#WebKitPrintOperation::failed is emitted before #WebKitPrintOperation::finished. +If the print dialog is not cancelled current print settings and page setup of @print_operation +are updated with options selected by the user when Print button is pressed in print dialog. +You can get the updated print settings and page setup by calling +webkit_print_operation_get_print_settings() and webkit_print_operation_get_page_setup() +after this method. + + + the #WebKitPrintOperationResponse of the print dialog + + + + + a #WebKitPrintOperation + + + + transient parent of the print dialog + + + + + + Set the current page setup of @print_operation. Current page setup is used for the +initial values of the print dialog when webkit_print_operation_run_dialog() is called. + + + + + + + a #WebKitPrintOperation + + + + a #GtkPageSetup to set + + + + + + Set the current print settings of @print_operation. Current print settings are used for +the initial values of the print dialog when webkit_print_operation_run_dialog() is called. + + + + + + + a #WebKitPrintOperation + + + + a #GtkPrintSettings to set + + + + + + The initial #GtkPageSetup for the print operation. + + + + The initial #GtkPrintSettings for the print operation. + + + + The #WebKitWebView that will be printed. + + + + + + + + + + Emitted when displaying the print dialog with webkit_print_operation_run_dialog(). +The returned #WebKitPrintCustomWidget will be added to the print dialog and +it will be owned by the @print_operation. However, the object is guaranteed +to be alive until the #WebKitPrintCustomWidget::apply is emitted. + + A #WebKitPrintCustomWidget that will be embedded in the dialog. + + + + + Emitted when an error occurs while printing. The given @error, of the domain +%WEBKIT_PRINT_ERROR, contains further details of the failure. +The #WebKitPrintOperation::finished signal is emitted after this one. + + + + + + the #GError that was triggered + + + + + + Emitted when the print operation has finished doing everything +required for printing. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values representing the response of the print dialog shown with +webkit_print_operation_run_dialog(). + + Print button was clicked in print dialog + + + Print dialog was cancelled + + + + Enum values used for determining the #WebKitWebContext process model. + + Deprecated 2.26. + + + Use one process + for each #WebKitWebView, while still allowing for some of them to + share a process in certain situations. The main advantage + of this process model is that the rendering process for a web view + can crash while the rest of the views keep working normally. This + process model is indicated for applications which may use a number + of web views and the content of in each must not interfere with the + rest — for example a full-fledged web browser with support for + multiple tabs. + + + + + + + + + + + + + + + + + + + + + + + + + + + Return the #WebKitURIRequest associated with the response decision. +Modifications to the returned object are <emphasis>not</emphasis> taken +into account when the request is sent over the network, and is intended +only to aid in evaluating whether a response decision should be taken or +not. To modify requests before they are sent over the network the +#WebKitPage::send-request signal can be used instead. + + + The URI request that is associated with this policy decision. + + + + + a #WebKitResponsePolicyDecision + + + + + + Gets the value of the #WebKitResponsePolicyDecision:response property. + + + The URI response that is associated with this policy decision. + + + + + a #WebKitResponsePolicyDecision + + + + + + Gets whether the MIME type of the response can be displayed in the #WebKitWebView +that triggered this policy decision request. See also webkit_web_view_can_show_mime_type(). + + + %TRUE if the MIME type of the response is supported or %FALSE otherwise + + + + + a #WebKitResponsePolicyDecision + + + + + + This property contains the #WebKitURIRequest associated with this +policy decision. + + + + This property contains the #WebKitURIResponse associated with this +policy decision. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values to specify the different ways in which a #WebKitWebView +can save its current web page into a self-contained file. + + Save the current page using the MHTML format. + + + + + + Close @dialog. When handling a #WebKitScriptDialog asynchronously (webkit_script_dialog_ref() +was called in #WebKitWebView::script-dialog callback), this function needs to be called to notify +that we are done with the script dialog. The dialog will be closed on destruction if this function +hasn't been called before. + + + + + + + a #WebKitScriptDialog + + + + + + This method is used for %WEBKIT_SCRIPT_DIALOG_CONFIRM and %WEBKIT_SCRIPT_DIALOG_BEFORE_UNLOAD_CONFIRM dialogs when +#WebKitWebView::script-dialog signal is emitted to set whether the user +confirmed the dialog or not. The default implementation of #WebKitWebView::script-dialog +signal sets %TRUE when the OK or Stay buttons are clicked and %FALSE otherwise. +It's an error to use this method with a #WebKitScriptDialog that is not of type +%WEBKIT_SCRIPT_DIALOG_CONFIRM or %WEBKIT_SCRIPT_DIALOG_BEFORE_UNLOAD_CONFIRM + + + + + + + a #WebKitScriptDialog + + + + whether user confirmed the dialog + + + + + + Get the dialog type of a #WebKitScriptDialog. + + + the #WebKitScriptDialogType of @dialog + + + + + a #WebKitScriptDialog + + + + + + Get the message of a #WebKitScriptDialog. + + + the message of @dialog. + + + + + a #WebKitScriptDialog + + + + + + Get the default text of a #WebKitScriptDialog of type %WEBKIT_SCRIPT_DIALOG_PROMPT. +It's an error to use this method with a #WebKitScriptDialog that is not of type +%WEBKIT_SCRIPT_DIALOG_PROMPT. + + + the default text of @dialog + + + + + a #WebKitScriptDialog + + + + + + This method is used for %WEBKIT_SCRIPT_DIALOG_PROMPT dialogs when +#WebKitWebView::script-dialog signal is emitted to set the text +entered by the user. The default implementation of #WebKitWebView::script-dialog +signal sets the text of the entry form when OK button is clicked, otherwise %NULL is set. +It's an error to use this method with a #WebKitScriptDialog that is not of type +%WEBKIT_SCRIPT_DIALOG_PROMPT. + + + + + + + a #WebKitScriptDialog + + + + the text to set + + + + + + Atomically increments the reference count of @dialog by one. This +function is MT-safe and may be called from any thread. + + + The passed in #WebKitScriptDialog + + + + + a #WebKitScriptDialog + + + + + + Atomically decrements the reference count of @dialog by one. If the +reference count drops to 0, all memory allocated by the #WebKitScriptdialog is +released. This function is MT-safe and may be called from any +thread. + + + + + + + a #WebKitScriptDialog + + + + + + + Enum values used for determining the type of #WebKitScriptDialog + + Alert script dialog, used to show a +message to the user. + + + Confirm script dialog, used to ask +confirmation to the user. + + + Prompt script dialog, used to ask +information to the user. + + + Before unload confirm dialog, +used to ask confirmation to leave the current page to the user. Since 2.12 + + + + + + Register @scheme as a CORS (Cross-origin resource sharing) enabled scheme. +This means that CORS requests are allowed. See W3C CORS specification +http://www.w3.org/TR/cors/. + + + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Register @scheme as a display isolated scheme. This means that pages cannot +display these URIs unless they are from the same scheme. + + + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Register @scheme as an empty document scheme. This means that +they are allowed to commit synchronously. + + + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Register @scheme as a local scheme. This means that other non-local pages +cannot link to or access URIs of this scheme. + + + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Register @scheme as a no-access scheme. This means that pages loaded +with this URI scheme cannot access pages loaded with any other URI scheme. + + + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Register @scheme as a secure scheme. This means that mixed +content warnings won't be generated for this scheme when +included by an HTTPS page. + + + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Whether @scheme is considered as a CORS enabled scheme. +See also webkit_security_manager_register_uri_scheme_as_cors_enabled(). + + + %TRUE if @scheme is a CORS enabled scheme or %FALSE otherwise. + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Whether @scheme is considered as a display isolated scheme. +See also webkit_security_manager_register_uri_scheme_as_display_isolated(). + + + %TRUE if @scheme is a display isolated scheme or %FALSE otherwise. + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Whether @scheme is considered as an empty document scheme. +See also webkit_security_manager_register_uri_scheme_as_empty_document(). + + + %TRUE if @scheme is an empty document scheme or %FALSE otherwise. + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Whether @scheme is considered as a local scheme. +See also webkit_security_manager_register_uri_scheme_as_local(). + + + %TRUE if @scheme is a local scheme or %FALSE otherwise. + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Whether @scheme is considered as a no-access scheme. +See also webkit_security_manager_register_uri_scheme_as_no_access(). + + + %TRUE if @scheme is a no-access scheme or %FALSE otherwise. + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + Whether @scheme is considered as a secure scheme. +See also webkit_security_manager_register_uri_scheme_as_secure(). + + + %TRUE if @scheme is a secure scheme or %FALSE otherwise. + + + + + a #WebKitSecurityManager + + + + a URI scheme + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Create a new security origin from the provided protocol, host and +port. + + + A #WebKitSecurityOrigin. + + + + + The protocol for the new origin + + + + The host for the new origin + + + + The port number for the new origin, or 0 to indicate the + default port for @protocol + + + + + + Create a new security origin from the provided URI. Components of +@uri other than protocol, host, and port do not affect the created +#WebKitSecurityOrigin. + + + A #WebKitSecurityOrigin. + + + + + The URI for the new origin + + + + + + Gets the hostname of @origin, or %NULL if @origin is opaque or if its +protocol does not require a host component. + + + The host of the #WebKitSecurityOrigin + + + + + a #WebKitSecurityOrigin + + + + + + Gets the port of @origin. This function will always return 0 if the +port is the default port for the given protocol. For example, +http://example.com has the same security origin as +http://example.com:80, and this function will return 0 for a +#WebKitSecurityOrigin constructed from either URI. It will also +return 0 if @origin is opaque. + + + The port of the #WebKitSecurityOrigin. + + + + + a #WebKitSecurityOrigin + + + + + + Gets the protocol of @origin, or %NULL if @origin is opaque. + + + The protocol of the #WebKitSecurityOrigin + + + + + a #WebKitSecurityOrigin + + + + + + Gets whether @origin is an opaque security origin, which does not +possess an associated protocol, host, or port. + + + %TRUE if @origin is opaque. + + + + + a #WebKitSecurityOrigin + + + + + + Atomically increments the reference count of @origin by one. +This function is MT-safe and may be called from any thread. + + + The passed #WebKitSecurityOrigin + + + + + a #WebKitSecurityOrigin + + + + + + Gets a string representation of @origin. The string representation +is a valid URI with only protocol, host, and port components. It may +be %NULL, but usually only if @origin is opaque. + + + a URI representing @origin. + + + + + a #WebKitSecurityOrigin + + + + + + Atomically decrements the reference count of @origin by one. +If the reference count drops to 0, all memory allocated by +#WebKitSecurityOrigin is released. This function is MT-safe and may be +called from any thread. + + + + + + + A #WebKitSecurityOrigin + + + + + + + + + Creates a new #WebKitSettings instance with default values. It must +be manually attached to a #WebKitWebView. +See also webkit_settings_new_with_settings(). + + + a new #WebKitSettings instance. + + + + + Creates a new #WebKitSettings instance with the given settings. It must +be manually attached to a #WebKitWebView. + + + a new #WebKitSettings instance. + + + + + name of first setting to set + + + + value of first setting, followed by more settings, + %NULL-terminated + + + + + + Convert @points to the equivalent value in pixels, based on the current +screen DPI. Applications can use this function to convert font size values +in points to font size values in pixels when setting the font size properties +of #WebKitSettings. + + + the equivalent font size in pixels. + + + + + the font size in points to convert to pixels + + + + + + Convert @pixels to the equivalent value in points, based on the current +screen DPI. Applications can use this function to convert font size values +in pixels to font size values in points when getting the font size properties +of #WebKitSettings. + + + the equivalent font size in points. + + + + + the font size in pixels to convert to points + + + + + + Get the #WebKitSettings:allow-file-access-from-file-urls property. + + + %TRUE If file access from file URLs is allowed or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:allow-modal-dialogs property. + + + %TRUE if it's allowed to create and run modal dialogs or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:allow-universal-access-from-file-urls property. + + + %TRUE If universal access from file URLs is allowed or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:auto-load-images property. + + + %TRUE If auto loading of images is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:cursive-font-family property. + + + The default font family used to display content marked with cursive font. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:default-charset property. + + + Default charset. + + + + + a #WebKitSettings + + + + + + + + + + + + + + + + + Gets the #WebKitSettings:default-font-size property. + + + The default font size, in pixels. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:default-monospace-font-size property. + + + Default monospace font size, in pixels. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:draw-compositing-indicators property. + + + %TRUE If compositing borders are drawn or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-accelerated-2d-canvas property. + + + %TRUE if accelerated 2D canvas is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-back-forward-navigation-gestures property. + + + %TRUE if horizontal swipe gesture will trigger back-forward navigaiton or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-caret-browsing property. + + + %TRUE If caret browsing is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-developer-extras property. + + + %TRUE If developer extras is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-dns-prefetching property. + + + %TRUE If DNS prefetching is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-encrypted-media property. + + + %TRUE if EncryptedMedia support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-frame-flattening property. + + + %TRUE If frame flattening is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-fullscreen property. + + + %TRUE If fullscreen support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-html5-database property. + + + %TRUE if IndexedDB support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-html5-local-storage property. + + + %TRUE If HTML5 local storage support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-hyperlink-auditing property. + + + %TRUE If hyper link auditing is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-java property. + + + %TRUE If Java is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-javascript property. + + + %TRUE If JavaScript is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-javascript-markup property. + + + %TRUE if JavaScript markup is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-media property. + + + %TRUE if media support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-media-capabilities property. + + + %TRUE if MediaCapabilities support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-media-stream property. + + + %TRUE If mediastream support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-mediasource property. + + + %TRUE If MediaSource support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-mock-capture-devices property. + + + %TRUE If mock capture devices is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-offline-web-application-cache property. + + + %TRUE If HTML5 offline web application cache support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-page-cache property. + + + %TRUE if page cache enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-plugins property. + + + %TRUE If plugins are enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-private-browsing property. + Use #WebKitWebView:is-ephemeral or #WebKitWebContext:is-ephemeral instead. + + + %TRUE If private browsing is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-resizable-text-areas property. + + + %TRUE If text areas can be resized or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-site-specific-quirks property. + + + %TRUE if site specific quirks are enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-smooth-scrolling property. + + + %TRUE if smooth scrolling is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-spatial-navigation property. + + + %TRUE If HTML5 spatial navigation support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-tabs-to-links property. + + + %TRUE If tabs to link is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-webaudio property. + + + %TRUE If webaudio support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-webgl property. + + + %TRUE If WebGL support is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-write-console-messages-to-stdout property. + + + %TRUE if writing console messages to stdout is enabled or %FALSE +otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:enable-xss-auditor property. + + + %TRUE If XSS auditing is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:fantasy-font-family property. + + + The default font family used to display content marked with fantasy font. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:hardware-acceleration-policy property. + + + a #WebKitHardwareAccelerationPolicy + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:javascript-can-access-clipboard property. + + + %TRUE If javascript-can-access-clipboard is enabled or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:javascript-can-open-windows-automatically property. + + + %TRUE If JavaScript can open window automatically or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:load-icons-ignoring-image-load-setting property. + + + %TRUE If site icon can be loaded irrespective of image loading preference or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:media-playback-allows-inline property. + + + %TRUE If inline playback is allowed for media + or %FALSE if only fullscreen playback is allowed. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:media-playback-requires-user-gesture property. + + + %TRUE If an user gesture is needed to play or load media + or %FALSE if no user gesture is needed. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:minimum-font-size property. + + + Minimum font size, in pixels. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:monospace-font-family property. + + + Default font family used to display content marked with monospace font. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:pictograph-font-family property. + + + The default font family used to display content marked with pictograph font. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:print-backgrounds property. + + + %TRUE If background images should be printed or %FALSE otherwise. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:sans-serif-font-family property. + + + The default font family used to display content marked with sans-serif font. + + + + + a #WebKitSettings + + + + + + Gets the #WebKitSettings:serif-font-family property. + + + The default font family used to display content marked with serif font. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:user-agent property. + + + The current value of the user-agent property. + + + + + a #WebKitSettings + + + + + + Get the #WebKitSettings:zoom-text-only property. + + + %TRUE If zoom level of the view should only affect the text + or %FALSE if all view contents should be scaled. + + + + + a #WebKitSettings + + + + + + Set the #WebKitSettings:allow-file-access-from-file-urls property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:allow-modal-dialogs property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:allow-universal-access-from-file-urls property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:auto-load-images property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:cursive-font-family property. + + + + + + + a #WebKitSettings + + + + the new default cursive font family + + + + + + Set the #WebKitSettings:default-charset property. + + + + + + + a #WebKitSettings + + + + default charset to be set + + + + + + Set the #WebKitSettings:default-font-family property. + + + + + + + a #WebKitSettings + + + + the new default font family + + + + + + Set the #WebKitSettings:default-font-size property. + + + + + + + a #WebKitSettings + + + + default font size to be set in pixels + + + + + + Set the #WebKitSettings:default-monospace-font-size property. + + + + + + + a #WebKitSettings + + + + default monospace font size to be set in pixels + + + + + + Set the #WebKitSettings:draw-compositing-indicators property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-accelerated-2d-canvas property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-back-forward-navigation-gestures property. + + + + + + + a #WebKitSettings + + + + value to be set + + + + + + Set the #WebKitSettings:enable-caret-browsing property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-developer-extras property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-dns-prefetching property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-encrypted-media property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-frame-flattening property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-fullscreen property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-html5-database property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-html5-local-storage property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-hyperlink-auditing property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-java property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-javascript property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-javascript-markup property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-media property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-media-capabilities property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-media-stream property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-mediasource property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-mock-capture-devices property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-offline-web-application-cache property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-page-cache property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-plugins property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-private-browsing property. + Use #WebKitWebView:is-ephemeral or #WebKitWebContext:is-ephemeral instead. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-resizable-text-areas property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-site-specific-quirks property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-smooth-scrolling property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-spatial-navigation property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-tabs-to-links property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-webaudio property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-webgl property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-write-console-messages-to-stdout property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:enable-xss-auditor property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:fantasy-font-family property. + + + + + + + a #WebKitSettings + + + + the new default fantasy font family + + + + + + Set the #WebKitSettings:hardware-acceleration-policy property. + + + + + + + a #WebKitSettings + + + + a #WebKitHardwareAccelerationPolicy + + + + + + Set the #WebKitSettings:javascript-can-access-clipboard property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:javascript-can-open-windows-automatically property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:load-icons-ignoring-image-load-setting property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:media-playback-allows-inline property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:media-playback-requires-user-gesture property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:minimum-font-size property. + + + + + + + a #WebKitSettings + + + + minimum font size to be set in pixels + + + + + + Set the #WebKitSettings:monospace-font-family property. + + + + + + + a #WebKitSettings + + + + the new default monospace font family + + + + + + Set the #WebKitSettings:pictograph-font-family property. + + + + + + + a #WebKitSettings + + + + the new default pictograph font family + + + + + + Set the #WebKitSettings:print-backgrounds property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Set the #WebKitSettings:sans-serif-font-family property. + + + + + + + a #WebKitSettings + + + + the new default sans-serif font family + + + + + + Set the #WebKitSettings:serif-font-family property. + + + + + + + a #WebKitSettings + + + + the new default serif font family + + + + + + Set the #WebKitSettings:user-agent property. + + + + + + + a #WebKitSettings + + + + The new custom user agent string or %NULL to use the default user agent + + + + + + Set the #WebKitSettings:user-agent property by appending the application details to the default user +agent. If no application name or version is given, the default user agent used will be used. If only +the version is given, the default engine version is used with the given application name. + + + + + + + a #WebKitSettings + + + + The application name used for the user agent or %NULL to use the default user agent. + + + + The application version for the user agent or %NULL to user the default version. + + + + + + Set the #WebKitSettings:zoom-text-only property. + + + + + + + a #WebKitSettings + + + + Value to be set + + + + + + Whether file access is allowed from file URLs. By default, when +something is loaded in a #WebKitWebView using a file URI, cross +origin requests to other file resources are not allowed. This +setting allows you to change that behaviour, so that it would be +possible to do a XMLHttpRequest of a local file, for example. + + + + Determine whether it's allowed to create and run modal dialogs +from a #WebKitWebView through JavaScript with +<function>window.showModalDialog</function>. If it's set to +%FALSE, the associated #WebKitWebView won't be able to create +new modal dialogs, so not even the #WebKitWebView::create +signal will be emitted. + + + + Whether or not JavaScript running in the context of a file scheme URL +should be allowed to access content from any origin. By default, when +something is loaded in a #WebKitWebView using a file scheme URL, +access to the local file system and arbitrary local storage is not +allowed. This setting allows you to change that behaviour, so that +it would be possible to use local storage, for example. + + + + Determines whether images should be automatically loaded or not. +On devices where network bandwidth is of concern, it might be +useful to turn this property off. + + + + The font family used as the default for content using a cursive font. + + + + The default text charset used when interpreting content with an unspecified charset. + + + + The font family to use as the default for content that does not specify a font. + + + + The default font size in pixels to use for content displayed if +no font size is specified. + + + + The default font size in pixels to use for content displayed in +monospace font if no font size is specified. + + + + Whether to draw compositing borders and repaint counters on layers drawn +with accelerated compositing. This is useful for debugging issues related +to web content that is composited with the GPU. + + + + Enable or disable accelerated 2D canvas. Accelerated 2D canvas is only available +if WebKit was compiled with a version of Cairo including the unstable CairoGL API. +When accelerated 2D canvas is enabled, WebKit may render some 2D canvas content +using hardware accelerated drawing operations. + + + + Enable or disable horizontal swipe gesture for back-forward navigation. + + + + Whether to enable accessibility enhanced keyboard navigation. + + + + Determines whether or not developer tools, such as the Web Inspector, are enabled. + + + + Determines whether or not to prefetch domain names. DNS prefetching attempts +to resolve domain names before a user tries to follow a link. + + + + Enable or disable support for Encrypted Media API on pages. +EncryptedMedia is an experimental JavaScript API for playing encrypted media in HTML. +This property will only work as intended if the EncryptedMedia feature is enabled at build time +with the ENABLE_ENCRYPTED_MEDIA flag. + +See https://www.w3.org/TR/encrypted-media/ + + + + Whether to enable the frame flattening. With this setting each subframe is expanded +to its contents, which will flatten all the frames to become one scrollable page. +On touch devices scrollable subframes on a page can result in a confusing user experience. + + + + Whether to enable the Javascript Fullscreen API. The API +allows any HTML element to request fullscreen display. See also +the current draft of the spec: +http://www.w3.org/TR/fullscreen/ + + + + Whether to enable HTML5 client-side SQL database support (IndexedDB). + + + + Whether to enable HTML5 local storage support. Local storage provides +simple synchronous storage access. + +HTML5 local storage specification is available at +http://dev.w3.org/html5/webstorage/. + + + + Determines whether or not hyperlink auditing is enabled. + +The hyperlink auditing specification is available at +http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#hyperlink-auditing. + + + + Determines whether or not Java is enabled on the page. + + + + Determines whether or not JavaScript executes within a page. + + + + Determines whether or not JavaScript markup is allowed in document. When this setting is disabled, +all JavaScript-related elements and attributes are removed from the document during parsing. Note that +executing JavaScript is still allowed if #WebKitSettings:enable-javascript is %TRUE. + + + + Enable or disable support for media playback on pages. This setting is enabled by +default. Disabling it means `<audio>`, `<track>` and `<video>` elements will have +playback support disabled. + + + + Enable or disable support for MediaCapabilities on pages. This +specification intends to provide APIs to allow websites to make an optimal +decision when picking media content for the user. The APIs will expose +information about the decoding and encoding capabilities for a given format +but also output capabilities to find the best match based on the device’s +display. + +See also https://wicg.github.io/media-capabilities/ + + + + Enable or disable support for MediaStream on pages. MediaStream +is an experimental proposal for allowing web pages to access +audio and video devices for capture. + +See also http://dev.w3.org/2011/webrtc/editor/getusermedia.html + + + + Enable or disable support for MediaSource on pages. MediaSource +extends HTMLMediaElement to allow JavaScript to generate media +streams for playback. + +See also http://www.w3.org/TR/media-source/ + + + + Enable or disable the Mock Capture Devices. Those are fake +Microphone and Camera devices to be used as MediaStream +sources. + + + + Whether to enable HTML5 offline web application cache support. Offline +web application cache allows web applications to run even when +the user is not connected to the network. + +HTML5 offline web application specification is available at +http://dev.w3.org/html5/spec/offline.html. + + + + Enable or disable the page cache. Disabling the page cache is +generally only useful for special circumstances like low-memory +scenarios or special purpose applications like static HTML +viewers. This setting only controls the Page Cache, this cache +is different than the disk-based or memory-based traditional +resource caches, its point is to make going back and forth +between pages much faster. For details about the different types +of caches and their purposes see: +http://webkit.org/blog/427/webkit-page-cache-i-the-basics/ + + + + Determines whether or not plugins on the page are enabled. + + + + Determines whether or not private browsing is enabled. Private browsing +will disable history, cache and form auto-fill for any pages visited. + Use #WebKitWebView:is-ephemeral or #WebKitWebsiteDataManager:is-ephemeral instead. + + + + Determines whether or not text areas can be resized. + + + + Whether to turn on site-specific quirks. Turning this on will +tell WebKit to use some site-specific workarounds for +better web compatibility. For example, older versions of +MediaWiki will incorrectly send to WebKit a CSS file with KHTML +workarounds. By turning on site-specific quirks, WebKit will +special-case this and other cases to make some specific sites work. + + + + Enable or disable smooth scrolling. + + + + Whether to enable Spatial Navigation. This feature consists in the ability +to navigate between focusable elements in a Web page, such as hyperlinks +and form controls, by using Left, Right, Up and Down arrow keys. +For example, if an user presses the Right key, heuristics determine whether +there is an element they might be trying to reach towards the right, and if +there are multiple elements, which element they probably wants. + + + + Determines whether the tab key cycles through the elements on the page. +When this setting is enabled, users will be able to focus the next element +in the page by pressing the tab key. If the selected element is editable, +then pressing tab key will insert the tab character. + + + + Enable or disable support for WebAudio on pages. WebAudio is an +experimental proposal for allowing web pages to generate Audio +WAVE data from JavaScript. The standard is currently a +work-in-progress by the W3C Audio Working Group. + +See also https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html + + + + Enable or disable support for WebGL on pages. WebGL is an experimental +proposal for allowing web pages to use OpenGL ES-like calls directly. The +standard is currently a work-in-progress by the Khronos Group. + + + + Enable or disable writing console messages to stdout. These are messages +sent to the console with console.log and related methods. + + + + Whether to enable the XSS auditor. This feature filters some kinds of +reflective XSS attacks on vulnerable web sites. + + + + The font family used as the default for content using a fantasy font. + + + + The #WebKitHardwareAccelerationPolicy to decide how to enable and disable +hardware acceleration. The default value %WEBKIT_HARDWARE_ACCELERATION_POLICY_ON_DEMAND +enables the hardware acceleration when the web contents request it, disabling it again +when no longer needed. It's possible to enforce hardware acceleration to be always enabled +by using %WEBKIT_HARDWARE_ACCELERATION_POLICY_ALWAYS. And it's also possible to disable it +completely using %WEBKIT_HARDWARE_ACCELERATION_POLICY_NEVER. Note that disabling hardware +acceleration might cause some websites to not render correctly or consume more CPU. + +Note that changing this setting might not be possible if hardware acceleration is not +supported by the hardware or the system. In that case you can get the value to know the +actual policy being used, but changing the setting will not have any effect. + + + + Whether JavaScript can access the clipboard. The default value is %FALSE. If +set to %TRUE, document.execCommand() allows cut, copy and paste commands. + + + + Whether JavaScript can open popup windows automatically without user +intervention. + + + + Determines whether a site can load favicons irrespective +of the value of #WebKitSettings:auto-load-images. + + + + Whether media playback is full-screen only or inline playback is allowed. +This is %TRUE by default, so media playback can be inline. Setting it to +%FALSE allows specifying that media playback should be always fullscreen. + + + + Whether a user gesture (such as clicking the play button) +would be required to start media playback or load media. This is off +by default, so media playback could start automatically. +Setting it on requires a gesture by the user to start playback, or to +load the media. + + + + The minimum font size in pixels used to display text. This setting +controls the absolute smallest size. Values other than 0 can +potentially break page layouts. + + + + The font family used as the default for content using a monospace font. + + + + The font family used as the default for content using a pictograph font. + + + + Whether background images should be drawn during printing. + + + + The font family used as the default for content using a sans-serif font. + + + + The font family used as the default for content using a serif font. + + + + The user-agent string used by WebKit. Unusual user-agent strings may cause web +content to render incorrectly or fail to run, as many web pages are written to +parse the user-agent strings of only the most popular browsers. Therefore, it's +typically better to not completely override the standard user-agent, but to use +webkit_settings_set_user_agent_with_application_details() instead. + +If this property is set to the empty string or %NULL, it will revert to the standard +user-agent. + + + + Whether #WebKitWebView:zoom-level affects only the +text of the page or all the contents. Other contents containing text +like form controls will be also affected by zoom factor when +this property is enabled. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to denote errors happening when creating snapshots of #WebKitWebView + + An error occurred when creating a webpage snapshot. + + + + + + + + + Enum values used to specify options when taking a snapshot +from a #WebKitWebView. + + Do not include any special options. + + + Whether to include in the +snapshot the highlight of the selected content. + + + Do not fill the background with white before +rendering the snapshot. Since 2.8 + + + + Enum values used to specify the region from which to get a #WebKitWebView +snapshot + + Specifies a snapshot only for the area that is +visible in the webview + + + A snapshot of the entire document. + + + + Enum values used to denote the TLS errors policy. + + Ignore TLS errors. + + + TLS errors will emit + #WebKitWebView::load-failed-with-tls-errors and, if the signal is handled, + finish the load. In case the signal is not handled, + #WebKitWebView::load-failed is emitted before the load finishes. + + + + + + Creates a new #WebKitURIRequest for the given URI. + + + a new #WebKitURIRequest + + + + + an URI + + + + + + Get the HTTP headers of a #WebKitURIRequest as a #SoupMessageHeaders. + + + a #SoupMessageHeaders with the HTTP headers of @request + or %NULL if @request is not an HTTP request. + + + + + a #WebKitURIRequest + + + + + + Get the HTTP method of the #WebKitURIRequest. + + + the HTTP method of the #WebKitURIRequest or %NULL if @request is not + an HTTP request. + + + + + a #WebKitURIRequest + + + + + + + + the uri of the #WebKitURIRequest + + + + + a #WebKitURIRequest + + + + + + Set the URI of @request + + + + + + + a #WebKitURIRequest + + + + an URI + + + + + + The URI to which the request will be made. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Get the expected content length of the #WebKitURIResponse. It can +be 0 if the server provided an incorrect or missing Content-Length. + + + the expected content length of @response. + + + + + a #WebKitURIResponse + + + + + + Get the HTTP headers of a #WebKitURIResponse as a #SoupMessageHeaders. + + + a #SoupMessageHeaders with the HTTP headers of @response + or %NULL if @response is not an HTTP response. + + + + + a #WebKitURIResponse + + + + + + + + the MIME type of the #WebKitURIResponse + + + + + a #WebKitURIResponse + + + + + + Get the status code of the #WebKitURIResponse as returned by +the server. It will normally be a #SoupKnownStatusCode, for +example %SOUP_STATUS_OK, though the server can respond with any +unsigned integer. + + + the status code of @response + + + + + a #WebKitURIResponse + + + + + + Get the suggested filename for @response, as specified by +the 'Content-Disposition' HTTP header, or %NULL if it's not +present. + + + the suggested filename or %NULL if + the 'Content-Disposition' HTTP header is not present. + + + + + a #WebKitURIResponse + + + + + + + + the uri of the #WebKitURIResponse + + + + + a #WebKitURIResponse + + + + + + The expected content length of the response. + + + + The HTTP headers of the response, or %NULL if the response is not an HTTP response. + + + + The MIME type of the response. + + + + The status code of the response as returned by the server. + + + + The suggested filename for the URI response. + + + + The URI for which the response was made. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Finish a #WebKitURISchemeRequest by setting the contents of the request and its mime type. + + + + + + + a #WebKitURISchemeRequest + + + + a #GInputStream to read the contents of the request + + + + the length of the stream or -1 if not known + + + + the content type of the stream or %NULL if not known + + + + + + Finish a #WebKitURISchemeRequest with a #GError. + + + + + + + a #WebKitURISchemeRequest + + + + a #GError that will be passed to the #WebKitWebView + + + + + + Get the URI path of @request + + + the URI path of @request + + + + + a #WebKitURISchemeRequest + + + + + + Get the URI scheme of @request + + + the URI scheme of @request + + + + + a #WebKitURISchemeRequest + + + + + + Get the URI of @request + + + the full URI of @request + + + + + a #WebKitURISchemeRequest + + + + + + Get the #WebKitWebView that initiated the request. + + + the #WebKitWebView that initiated @request. + + + + + a #WebKitURISchemeRequest + + + + + + + + + + + + + Type definition for a function that will be called back when an URI request is +made for a user registered URI scheme. + + + + + + + the #WebKitURISchemeRequest + + + + user data passed to the callback + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Obtain the identifier previously used to save the @user_content_filter in the +#WebKitUserContentFilterStore. + + + the identifier for the filter + + + + + A #WebKitUserContentFilter + + + + + + Atomically increments the reference count of @user_content_filter by one. +This function is MT-safe and may be called from any thread. + + + + + + + A #WebKitUserContentFilter + + + + + + Atomically decrements the reference count of @user_content_filter by one. +If the reference count drops to 0, all the memory allocated by the +#WebKitUserContentFilter is released. This function is MT-safe and may +be called from any thread. + + + + + + + A #WebKitUserContentFilter + + + + + + + + The JSON source for a content filter is invalid. + + + The requested content filter could not be found. + + + + + + + + + + + Create a new #WebKitUserContentFilterStore to manipulate filters stored at @storage_path. +The path must point to a local filesystem, and will be created if needed. + + + a newly created #WebKitUserContentFilterStore + + + + + path where data for filters will be stored on disk + + + + + + Asynchronously retrieve a list of the identifiers for all the stored filters. + +When the operation is finished, @callback will be invoked, which then can use +webkit_user_content_filter_store_fetch_identifiers_finish() to obtain the list of +filter identifiers. + + + + + + + a #WebKitUserContentFilterStore + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the removal is completed + + + + the data to pass to the callback function + + + + + + Finishes an asynchronous fetch of the list of identifiers for the stored filters previously +started with webkit_user_content_filter_store_fetch_identifiers(). + + + a %NULL-terminated list of filter identifiers. + + + + + + + a #WebKitUserContentFilterStore + + + + a #GAsyncResult + + + + + + + + The storage path for user content filters. + + + + + a #WebKitUserContentFilterStore + + + + + + Asynchronously load a content filter given its @identifier. The filter must have been +previously stored using webkit_user_content_filter_store_save(). + +When the operation is finished, @callback will be invoked, which then can use +webkit_user_content_filter_store_load_finish() to obtain the resulting filter. + + + + + + + a #WebKitUserContentFilterStore + + + + a filter identifier + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the load is completed + + + + the data to pass to the callback function + + + + + + Finishes an asynchronous filter load previously started with +webkit_user_content_filter_store_load(). + + + a #WebKitUserContentFilter, or %NULL if the load failed + + + + + a #WebKitUserContentFilterStore + + + + a #GAsyncResult + + + + + + Asynchronously remove a content filter given its @identifier. + +When the operation is finished, @callback will be invoked, which then can use +webkit_user_content_filter_store_remove_finish() to check whether the removal was +successful. + + + + + + + a #WebKitUserContentFilterStore + + + + a filter identifier + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the removal is completed + + + + the data to pass to the callback function + + + + + + Finishes an asynchronous filter removal previously started with +webkit_user_content_filter_store_remove(). + + + whether the removal was successful + + + + + a #WebKitUserContentFilterStore + + + + a #GAsyncResult + + + + + + Asynchronously save a content filter from a source rule set in the +[WebKit content extesions JSON format](https://webkit.org/blog/3476/content-blockers-first-look/). + +The @identifier can be used afterwards to refer to the filter when using +webkit_user_content_filter_store_remove() and webkit_user_content_filter_store_load(). +When the @identifier has been used in the past, the new filter source will replace +the one saved beforehand for the same identifier. + +When the operation is finished, @callback will be invoked, which then can use +webkit_user_content_filter_store_save_finish() to obtain the resulting filter. + + + + + + + a #WebKitUserContentFilterStore + + + + a string used to identify the saved filter + + + + #GBytes containing the rule set in JSON format + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when saving is completed + + + + the data to pass to the callback function + + + + + + Finishes an asynchronous filter save previously started with +webkit_user_content_filter_store_save(). + + + a #WebKitUserContentFilter, or %NULL if saving failed + + + + + a #WebKitUserContentFilterStore + + + + a #GAsyncResult + + + + + + Asynchronously save a content filter from the contents of a file, which must be +native to the platform, as checked by g_file_is_native(). See +webkit_user_content_filter_store_save() for more details. + +When the operation is finished, @callback will be invoked, which then can use +webkit_user_content_filter_store_save_finish() to obtain the resulting filter. + + + + + + + a #WebKitUserContentFilterStore + + + + a string used to identify the saved filter + + + + a #GFile containing the rule set in JSON format + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when saving is completed + + + + the data to pass to the callback function + + + + + + Finishes and asynchronous filter save previously started with +webkit_user_content_filter_store_save_from_file(). + + + a #WebKitUserContentFilter, or %NULL if saving failed. + + + + + a #WebKitUserContentFilterStore + + + + a #GAsyncResult + + + + + + The directory used for filter storage. This path is used as the base +directory where user content filters are stored on disk. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specifies in which frames user style sheets are to be inserted in. + + Insert the user style + sheet in all the frames loaded by the web view, including + nested frames. This is the default. + + + Insert the user style + sheet *only* in the top-level frame loaded by the web view, + and *not* in the nested frames. + + + + + + Creates a new user content manager. + + + A #WebKitUserContentManager + + + + + Adds a #WebKitUserContentFilter to the given #WebKitUserContentManager. +The same #WebKitUserContentFilter can be reused with multiple +#WebKitUserContentManager instances. + +Filters need to be saved and loaded from #WebKitUserContentFilterStore. + + + + + + + A #WebKitUserContentManager + + + + A #WebKitUserContentFilter + + + + + + Adds a #WebKitUserScript to the given #WebKitUserContentManager. +The same #WebKitUserScript can be reused with multiple +#WebKitUserContentManager instances. + + + + + + + A #WebKitUserContentManager + + + + A #WebKitUserScript + + + + + + Adds a #WebKitUserStyleSheet to the given #WebKitUserContentManager. +The same #WebKitUserStyleSheet can be reused with multiple +#WebKitUserContentManager instances. + + + + + + + A #WebKitUserContentManager + + + + A #WebKitUserStyleSheet + + + + + + Registers a new user script message handler. After it is registered, +scripts can use `window.webkit.messageHandlers.&lt;name&gt;.postMessage(value)` +to send messages. Those messages are received by connecting handlers +to the #WebKitUserContentManager::script-message-received signal. The +handler name is used as the detail of the signal. To avoid race +conditions between registering the handler name, and starting to +receive the signals, it is recommended to connect to the signal +*before* registering the handler name: + +<informalexample><programlisting> +WebKitWebView *view = webkit_web_view_new (); +WebKitUserContentManager *manager = webkit_web_view_get_user_content_manager (); +g_signal_connect (manager, "script-message-received::foobar", + G_CALLBACK (handle_script_message), NULL); +webkit_user_content_manager_register_script_message_handler (manager, "foobar"); +</programlisting></informalexample> + +Registering a script message handler will fail if the requested +name has been already registered before. + + + %TRUE if message handler was registered successfully, or %FALSE otherwise. + + + + + A #WebKitUserContentManager + + + + Name of the script message channel + + + + + + Registers a new user script message handler in script world with name @world_name. +See webkit_user_content_manager_register_script_message_handler() for full description. + +Registering a script message handler will fail if the requested +name has been already registered before. + + + %TRUE if message handler was registered successfully, or %FALSE otherwise. + + + + + A #WebKitUserContentManager + + + + Name of the script message channel + + + + the name of a #WebKitScriptWorld + + + + + + Removes all content filters from the given #WebKitUserContentManager. + + + + + + + A #WebKitUserContentManager + + + + + + Removes all user scripts from the given #WebKitUserContentManager + + + + + + + A #WebKitUserContentManager + + + + + + Removes all user style sheets from the given #WebKitUserContentManager. + + + + + + + A #WebKitUserContentManager + + + + + + Removes a filter from the given #WebKitUserContentManager. + +Since 2.24 + + + + + + + A #WebKitUserContentManager + + + + A #WebKitUserContentFilter + + + + + + Removes a filter from the given #WebKitUserContentManager given the +identifier of a #WebKitUserContentFilter as returned by +webkit_user_content_filter_get_identifier(). + + + + + + + A #WebKitUserContentManager + + + + Filter identifier + + + + + + Unregisters a previously registered message handler. + +Note that this does *not* disconnect handlers for the +#WebKitUserContentManager::script-message-received signal; +they will be kept connected, but the signal will not be emitted +unless the handler name is registered again. + +See also webkit_user_content_manager_register_script_message_handler(). + + + + + + + A #WebKitUserContentManager + + + + Name of the script message channel + + + + + + Unregisters a previously registered message handler in script world with name @world_name. + +Note that this does *not* disconnect handlers for the +#WebKitUserContentManager::script-message-received signal; +they will be kept connected, but the signal will not be emitted +unless the handler name is registered again. + +See also webkit_user_content_manager_register_script_message_handler_in_world(). + + + + + + + A #WebKitUserContentManager + + + + Name of the script message channel + + + + the name of a #WebKitScriptWorld + + + + + + + + + + + + This signal is emitted when JavaScript in a web view calls +<code>window.webkit.messageHandlers.&lt;name&gt;.postMessage()</code>, after registering +<code>&lt;name&gt;</code> using +webkit_user_content_manager_register_script_message_handler() + + + + + + the #WebKitJavascriptResult holding the value received from the JavaScript world. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new user script. Scripts can be applied to some URIs +only by passing non-null values for @whitelist or @blacklist. Passing a +%NULL whitelist implies that all URIs are on the whitelist. The script +is applied if an URI matches the whitelist and not the blacklist. +URI patterns must be of the form `[protocol]://[host]/[path]`, where the +*host* and *path* components can contain the wildcard character (`*`) to +represent zero or more other characters. + + + A new #WebKitUserScript + + + + + Source code of the user script. + + + + A #WebKitUserContentInjectedFrames value + + + + A #WebKitUserScriptInjectionTime value + + + + A whitelist of URI patterns or %NULL + + + + + + A blacklist of URI patterns or %NULL + + + + + + + + Creates a new user script for script world with name @world_name. +See webkit_user_script_new() for a full description. + + + A new #WebKitUserScript + + + + + Source code of the user script. + + + + A #WebKitUserContentInjectedFrames value + + + + A #WebKitUserScriptInjectionTime value + + + + the name of a #WebKitScriptWorld + + + + A whitelist of URI patterns or %NULL + + + + + + A blacklist of URI patterns or %NULL + + + + + + + + Atomically increments the reference count of @user_script by one. +This function is MT-safe and may be called from any thread. + + + The passed #WebKitUserScript + + + + + a #WebKitUserScript + + + + + + Atomically decrements the reference count of @user_script by one. +If the reference count drops to 0, all memory allocated by +#WebKitUserScript is released. This function is MT-safe and may be called +from any thread. + + + + + + + a #WebKitUserScript + + + + + + + Specifies at which place of documents an user script will be inserted. + + Insert the code of the user + script at the beginning of loaded documents. This is the default. + + + Insert the code of the user + script at the end of the loaded documents. + + + + Specifies how to treat an user style sheet. + + The style sheet is an user style sheet, + its contents always override other style sheets. This is the default. + + + The style sheet will be treated as if + it was provided by the loaded documents. That means other user style + sheets may still override it. + + + + + + Creates a new user style sheet. Style sheets can be applied to some URIs +only by passing non-null values for @whitelist or @blacklist. Passing a +%NULL whitelist implies that all URIs are on the whitelist. The style +sheet is applied if an URI matches the whitelist and not the blacklist. +URI patterns must be of the form `[protocol]://[host]/[path]`, where the +*host* and *path* components can contain the wildcard character (`*`) to +represent zero or more other characters. + + + A new #WebKitUserStyleSheet + + + + + Source code of the user style sheet. + + + + A #WebKitUserContentInjectedFrames value + + + + A #WebKitUserStyleLevel + + + + A whitelist of URI patterns or %NULL + + + + + + A blacklist of URI patterns or %NULL + + + + + + + + Creates a new user style sheet for script world with name @world_name. +See webkit_user_style_sheet_new() for a full description. + + + A new #WebKitUserStyleSheet + + + + + Source code of the user style sheet. + + + + A #WebKitUserContentInjectedFrames value + + + + A #WebKitUserStyleLevel + + + + the name of a #WebKitScriptWorld + + + + A whitelist of URI patterns or %NULL + + + + + + A blacklist of URI patterns or %NULL + + + + + + + + Atomically increments the reference count of @user_style_sheet by one. +This function is MT-safe and may be called from any thread. + + + The passed #WebKitUserStyleSheet + + + + + a #WebKitUserStyleSheet + + + + + + Atomically decrements the reference count of @user_style_sheet by one. +If the reference count drops to 0, all memory allocated by +#WebKitUserStyleSheet is released. This function is MT-safe and may be +called from any thread. + + + + + + + a #WebKitUserStyleSheet + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Create a new #WebKitWebContext + + + a newly created #WebKitWebContext + + + + + Create a new ephemeral #WebKitWebContext. An ephemeral #WebKitWebContext is a context +created with an ephemeral #WebKitWebsiteDataManager. This is just a convenient method +to create ephemeral contexts without having to create your own #WebKitWebsiteDataManager. +All #WebKitWebView<!-- -->s associated with this context will also be ephemeral. Websites will +not store any data in the client storage. +This is normally used to implement private instances. + + + a new ephemeral #WebKitWebContext. + + + + + Create a new #WebKitWebContext with a #WebKitWebsiteDataManager. + + + a newly created #WebKitWebContext + + + + + a #WebKitWebsiteDataManager + + + + + + Gets the default web context + + + a #WebKitWebContext + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Adds a path to be mounted in the sandbox. @path must exist before any web process +has been created otherwise it will be silently ignored. It is a fatal error to +add paths after a web process has been spawned. + +Paths in directories such as `/sys`, `/proc`, and `/dev` or all of `/` +are not valid. + +See also webkit_web_context_set_sandbox_enabled() + + + + + + + a #WebKitWebContext + + + + an absolute path to mount in the sandbox + + + + if %TRUE the path will be read-only + + + + + + Ignore further TLS errors on the @host for the certificate present in @info. + + + + + + + a #WebKitWebContext + + + + a #GTlsCertificate + + + + the host for which a certificate is to be allowed + + + + + + Clears all resources currently cached. +See also webkit_web_context_set_cache_model(). + + + + + + + a #WebKitWebContext + + + + + + Requests downloading of the specified URI string. The download operation +will not be associated to any #WebKitWebView, if you are interested in +starting a download from a particular #WebKitWebView use +webkit_web_view_download_uri() instead. + + + a new #WebKitDownload representing + the download operation. + + + + + a #WebKitWebContext + + + + the URI to download + + + + + + Returns the current cache model. For more information about this +value check the documentation of the function +webkit_web_context_set_cache_model(). + + + the current #WebKitCacheModel + + + + + the #WebKitWebContext + + + + + + Get the #WebKitCookieManager of the @context's #WebKitWebsiteDataManager. + + + the #WebKitCookieManager of @context. + + + + + a #WebKitWebContext + + + + + + Get the #WebKitFaviconDatabase associated with @context. + +To initialize the database you need to call +webkit_web_context_set_favicon_database_directory(). + + + the #WebKitFaviconDatabase of @context. + + + + + a #WebKitWebContext + + + + + + Get the directory path being used to store the favicons database +for @context, or %NULL if +webkit_web_context_set_favicon_database_directory() hasn't been +called yet. + +This function will always return the same path after having called +webkit_web_context_set_favicon_database_directory() for the first +time. + + + the path of the directory of the favicons +database associated with @context, or %NULL. + + + + + a #WebKitWebContext + + + + + + Get the #WebKitGeolocationManager of @context. + + + the #WebKitGeolocationManager of @context. + + + + + a #WebKitWebContext + + + + + + Asynchronously get the list of installed plugins. + +When the operation is finished, @callback will be called. You can then call +webkit_web_context_get_plugins_finish() to get the result of the operation. + + + + + + + a #WebKitWebContext + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_web_context_get_plugins. + + + a #GList of #WebKitPlugin. You must free the #GList with + g_list_free() and unref the #WebKitPlugin<!-- -->s with g_object_unref() when you're done with them. + + + + + + + a #WebKitWebContext + + + + a #GAsyncResult + + + + + + Returns the current process model. For more information about this value +see webkit_web_context_set_process_model(). + + + the current #WebKitProcessModel + + + + + the #WebKitWebContext + + + + + + Get whether sandboxing is currently enabled. + + + %TRUE if sandboxing is enabled, or %FALSE otherwise. + + + + + a #WebKitWebContext + + + + + + Get the #WebKitSecurityManager of @context. + + + the #WebKitSecurityManager of @context. + + + + + a #WebKitWebContext + + + + + + Get whether spell checking feature is currently enabled. + + + %TRUE If spell checking is enabled, or %FALSE otherwise. + + + + + a #WebKitWebContext + + + + + + Get the the list of spell checking languages associated with +@context, or %NULL if no languages have been previously set. + +See webkit_web_context_set_spell_checking_languages() for more +details on the format of the languages in the list. + + + A %NULL-terminated + array of languages if available, or %NULL otherwise. + + + + + + + a #WebKitWebContext + + + + + + Get the TLS errors policy of @context + + + a #WebKitTLSErrorsPolicy + + + + + a #WebKitWebContext + + + + + + Gets the maximum number of web processes that can be created at the same time for the @context. + +This function is now deprecated and always returns 0 (no limit). See also webkit_web_context_set_web_process_count_limit(). + + + the maximum limit of web processes, or 0 if there isn't a limit. + + + + + the #WebKitWebContext + + + + + + Get the #WebKitWebsiteDataManager of @context. + + + a #WebKitWebsiteDataManager + + + + + the #WebKitWebContext + + + + + + Sets initial desktop notification permissions for the @context. +@allowed_origins and @disallowed_origins must each be #GList of +#WebKitSecurityOrigin objects representing origins that will, +respectively, either always or never have permission to show desktop +notifications. No #WebKitNotificationPermissionRequest will ever be +generated for any of the security origins represented in +@allowed_origins or @disallowed_origins. This function is necessary +because some webpages proactively check whether they have permission +to display notifications without ever creating a permission request. + +This function only affects web processes that have not already been +created. The best time to call it is when handling +#WebKitWebContext::initialize-notification-permissions so as to +ensure that new web processes receive the most recent set of +permissions. + + + + + + + the #WebKitWebContext + + + + a #GList of security origins + + + + + + a #GList of security origins + + + + + + + + Get whether automation is allowed in @context. +See also webkit_web_context_set_automation_allowed(). + + + %TRUE if automation is allowed or %FALSE otherwise. + + + + + the #WebKitWebContext + + + + + + Get whether a #WebKitWebContext is ephemeral. + + + %TRUE if @context is ephemeral or %FALSE otherwise. + + + + + the #WebKitWebContext + + + + + + Resolve the domain name of the given @hostname in advance, so that if a URI +of @hostname is requested the load will be performed more quickly. + + + + + + + a #WebKitWebContext + + + + a hostname to be resolved + + + + + + Register @scheme in @context, so that when an URI request with @scheme is made in the +#WebKitWebContext, the #WebKitURISchemeRequestCallback registered will be called with a +#WebKitURISchemeRequest. +It is possible to handle URI scheme requests asynchronously, by calling g_object_ref() on the +#WebKitURISchemeRequest and calling webkit_uri_scheme_request_finish() later +when the data of the request is available or +webkit_uri_scheme_request_finish_error() in case of error. + +<informalexample><programlisting> +static void +about_uri_scheme_request_cb (WebKitURISchemeRequest *request, + gpointer user_data) +{ + GInputStream *stream; + gsize stream_length; + const gchar *path; + + path = webkit_uri_scheme_request_get_path (request); + if (!g_strcmp0 (path, "plugins")) { + /<!-- -->* Create a GInputStream with the contents of plugins about page, and set its length to stream_length *<!-- -->/ + } else if (!g_strcmp0 (path, "memory")) { + /<!-- -->* Create a GInputStream with the contents of memory about page, and set its length to stream_length *<!-- -->/ + } else if (!g_strcmp0 (path, "applications")) { + /<!-- -->* Create a GInputStream with the contents of applications about page, and set its length to stream_length *<!-- -->/ + } else if (!g_strcmp0 (path, "example")) { + gchar *contents; + + contents = g_strdup_printf ("&lt;html&gt;&lt;body&gt;&lt;p&gt;Example about page&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;"); + stream_length = strlen (contents); + stream = g_memory_input_stream_new_from_data (contents, stream_length, g_free); + } else { + GError *error; + + error = g_error_new (ABOUT_HANDLER_ERROR, ABOUT_HANDLER_ERROR_INVALID, "Invalid about:%s page.", path); + webkit_uri_scheme_request_finish_error (request, error); + g_error_free (error); + return; + } + webkit_uri_scheme_request_finish (request, stream, stream_length, "text/html"); + g_object_unref (stream); +} +</programlisting></informalexample> + + + + + + + a #WebKitWebContext + + + + the network scheme to register + + + + a #WebKitURISchemeRequestCallback + + + + data to pass to callback function + + + + destroy notify for @user_data + + + + + + Set an additional directory where WebKit will look for plugins. + + + + + + + a #WebKitWebContext + + + + the directory to add + + + + + + Set whether automation is allowed in @context. When automation is enabled the browser could +be controlled by another process by requesting an automation session. When a new automation +session is requested the signal #WebKitWebContext::automation-started is emitted. +Automation is disabled by default, so you need to explicitly call this method passing %TRUE +to enable it. + +Note that only one #WebKitWebContext can have automation enabled, so this will do nothing +if there's another #WebKitWebContext with automation already enabled. + + + + + + + the #WebKitWebContext + + + + value to set + + + + + + Specifies a usage model for WebViews, which WebKit will use to +determine its caching behavior. All web views follow the cache +model. This cache model determines the RAM and disk space to use +for caching previously viewed content . + +Research indicates that users tend to browse within clusters of +documents that hold resources in common, and to revisit previously +visited documents. WebKit and the frameworks below it include +built-in caches that take advantage of these patterns, +substantially improving document load speed in browsing +situations. The WebKit cache model controls the behaviors of all of +these caches, including various WebCore caches. + +Browsers can improve document load speed substantially by +specifying %WEBKIT_CACHE_MODEL_WEB_BROWSER. Applications without a +browsing interface can reduce memory usage substantially by +specifying %WEBKIT_CACHE_MODEL_DOCUMENT_VIEWER. The default value is +%WEBKIT_CACHE_MODEL_WEB_BROWSER. + + + + + + + the #WebKitWebContext + + + + a #WebKitCacheModel + + + + + + Set the directory where disk cache files will be stored +This method must be called before loading anything in this context, otherwise +it will not have any effect. + +Note that this method overrides the directory set in the #WebKitWebsiteDataManager, +but it doesn't change the value returned by webkit_website_data_manager_get_disk_cache_directory() +since the #WebKitWebsiteDataManager is immutable. + Use webkit_web_context_new_with_website_data_manager() instead. + + + + + + + a #WebKitWebContext + + + + the directory to set + + + + + + Set the directory path to be used to store the favicons database +for @context on disk. Passing %NULL as @path means using the +default directory for the platform (see g_get_user_cache_dir()). + +Calling this method also means enabling the favicons database for +its use from the applications, so that's why it's expected to be +called only once. Further calls for the same instance of +#WebKitWebContext won't cause any effect. + + + + + + + a #WebKitWebContext + + + + an absolute path to the icon database +directory or %NULL to use the defaults + + + + + + Set the network proxy settings to be used by connections started in @context. +By default %WEBKIT_NETWORK_PROXY_MODE_DEFAULT is used, which means that the +system settings will be used (g_proxy_resolver_get_default()). +If you want to override the system default settings, you can either use +%WEBKIT_NETWORK_PROXY_MODE_NO_PROXY to make sure no proxies are used at all, +or %WEBKIT_NETWORK_PROXY_MODE_CUSTOM to provide your own proxy settings. +When @proxy_mode is %WEBKIT_NETWORK_PROXY_MODE_CUSTOM @proxy_settings must be +a valid #WebKitNetworkProxySettings; otherwise, @proxy_settings must be %NULL. + + + + + + + a #WebKitWebContext + + + + a #WebKitNetworkProxyMode + + + + a #WebKitNetworkProxySettings, or %NULL + + + + + + Set the list of preferred languages, sorted from most desirable +to least desirable. The list will be used to build the "Accept-Language" +header that will be included in the network requests started by +the #WebKitWebContext. + + + + + + + a #WebKitWebContext + + + + a %NULL-terminated list of language identifiers + + + + + + + + Specifies a process model for WebViews, which WebKit will use to +determine how auxiliary processes are handled. + +%WEBKIT_PROCESS_MODEL_MULTIPLE_SECONDARY_PROCESSES will use +one process per view most of the time, while still allowing for web +views to share a process when needed (for example when different +views interact with each other). Using this model, when a process +hangs or crashes, only the WebViews using it stop working, while +the rest of the WebViews in the application will still function +normally. + +%WEBKIT_PROCESS_MODEL_SHARED_SECONDARY_PROCESS is deprecated since 2.26, +using it has no effect for security reasons. + +This method **must be called before any web process has been created**, +as early as possible in your application. Calling it later will make +your application crash. + + + + + + + the #WebKitWebContext + + + + a #WebKitProcessModel + + + + + + Set whether WebKit subprocesses will be sandboxed, limiting access to the system. + +This method **must be called before any web process has been created**, +as early as possible in your application. Calling it later is a fatal error. + +This is only implemented on Linux and is a no-op otherwise. + + + + + + + a #WebKitWebContext + + + + if %TRUE enable sandboxing + + + + + + Enable or disable the spell checking feature. + + + + + + + a #WebKitWebContext + + + + Value to be set + + + + + + Set the list of spell checking languages to be used for spell +checking. + +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. + +You need to call this function with a valid list of languages at +least once in order to properly enable the spell checking feature +in WebKit. + + + + + + + a #WebKitWebContext + + + + a %NULL-terminated list of spell checking languages + + + + + + + + Set the TLS errors policy of @context as @policy + + + + + + + a #WebKitWebContext + + + + a #WebKitTLSErrorsPolicy + + + + + + Set the directory where WebKit will look for Web Extensions. +This method must be called before loading anything in this context, +otherwise it will not have any effect. You can connect to +#WebKitWebContext::initialize-web-extensions to call this method +before anything is loaded. + + + + + + + a #WebKitWebContext + + + + the directory to add + + + + + + Set user data to be passed to Web Extensions on initialization. +The data will be passed to the +#WebKitWebExtensionInitializeWithUserDataFunction. +This method must be called before loading anything in this context, +otherwise it will not have any effect. You can connect to +#WebKitWebContext::initialize-web-extensions to call this method +before anything is loaded. + + + + + + + a #WebKitWebContext + + + + a #GVariant + + + + + + Sets the maximum number of web processes that can be created at the same time for the @context. +The default value is 0 and means no limit. + +This function is now deprecated and does nothing for security reasons. + + + + + + + the #WebKitWebContext + + + + the maximum number of web processes + + + + + + The directory where local storage data will be saved. + Use #WebKitWebsiteDataManager:local-storage-directory instead. + + + + The #WebKitWebsiteDataManager associated with this context. + + + + + + + + + + This signal is emitted when a new automation request is made. +Note that it will never be emitted if automation is not enabled in @context, +see webkit_web_context_set_automation_allowed() for more details. + + + + + + the #WebKitAutomationSession associated with this event + + + + + + This signal is emitted when a new download request is made. + + + + + + the #WebKitDownload associated with this event + + + + + + This signal is emitted when a #WebKitWebContext needs to set +initial notification permissions for a web process. It is emitted +when a new web process is about to be launched, and signals the +most appropriate moment to use +webkit_web_context_initialize_notification_permissions(). If no +notification permissions have changed since the last time this +signal was emitted, then there is no need to call +webkit_web_context_initialize_notification_permissions() again. + + + + + + This signal is emitted when a new web process is about to be +launched. It signals the most appropriate moment to use +webkit_web_context_set_web_extensions_initialization_user_data() +and webkit_web_context_set_web_extensions_directory(). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Request @inspector to be attached. The signal #WebKitWebInspector::attach +will be emitted. If the inspector is already attached it does nothing. + + + + + + + a #WebKitWebInspector + + + + + + Request @inspector to be closed. + + + + + + + a #WebKitWebInspector + + + + + + Request @inspector to be detached. The signal #WebKitWebInspector::detach +will be emitted. If the inspector is already detached it does nothing. + + + + + + + a #WebKitWebInspector + + + + + + Get the height that the inspector view should have when +it's attached. If the inspector view is not attached this +returns 0. + + + the height of the inspector view when attached + + + + + a #WebKitWebInspector + + + + + + Whether the @inspector can be attached to the same window that contains +the inspected view. + + + %TRUE if there is enough room for the inspector view inside the + window that contains the inspected view, or %FALSE otherwise. + + + + + a #WebKitWebInspector + + + + + + Get the URI that is currently being inspected. This can be %NULL if +nothing has been loaded yet in the inspected view, if the inspector +has been closed or when inspected view was loaded from a HTML string +instead of a URI. + + + the URI that is currently being inspected or %NULL + + + + + a #WebKitWebInspector + + + + + + Get the #WebKitWebViewBase used to display the inspector. +This might be %NULL if the inspector hasn't been loaded yet, +or it has been closed. + + + the #WebKitWebViewBase used to display the inspector or %NULL + + + + + a #WebKitWebInspector + + + + + + Whether the @inspector view is currently attached to the same window that contains +the inspected view. + + + %TRUE if @inspector is currently attached or %FALSE otherwise + + + + + a #WebKitWebInspector + + + + + + Request @inspector to be shown. + + + + + + + a #WebKitWebInspector + + + + + + The height that the inspector view should have when it is attached. + + + + Whether the @inspector can be attached to the same window that contains +the inspected view. + + + + The URI that is currently being inspected. + + + + + + + + + + Emitted when the inspector is requested to be attached to the window +where the inspected web view is. +If this signal is not handled the inspector view will be automatically +attached to the inspected view, so you only need to handle this signal +if you want to attach the inspector view yourself (for example, to add +the inspector view to a browser tab). + +To prevent the inspector view from being attached you can connect to this +signal and simply return %TRUE. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + Emitted when the inspector should be shown. + +If the inspector is not attached the inspector window should be shown +on top of any other windows. +If the inspector is attached the inspector view should be made visible. +For example, if the inspector view is attached using a tab in a browser +window, the browser window should be raised and the tab containing the +inspector view should be the active one. +In both cases, if this signal is not handled, the default implementation +calls gtk_window_present() on the current toplevel #GtkWindow of the +inspector view. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + Emitted when the inspector page is closed. If you are using your own +inspector window, you should connect to this signal and destroy your +window. + + + + + + Emitted when the inspector is requested to be detached from the window +it is currently attached to. The inspector is detached when the inspector page +is about to be closed, and this signal is emitted right before +#WebKitWebInspector::closed, or when the user clicks on the detach button +in the inspector view to show the inspector in a separate window. In this case +the signal #WebKitWebInspector::open-window is emitted after this one. + +To prevent the inspector view from being detached you can connect to this +signal and simply return %TRUE. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + Emitted when the inspector is requested to open in a separate window. +If this signal is not handled, a #GtkWindow with the inspector will be +created and shown, so you only need to handle this signal if you want +to use your own window. +This signal is emitted after #WebKitWebInspector::detach to show +the inspector in a separate window after being detached. + +To prevent the inspector from being shown you can connect to this +signal and simply return %TRUE + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values used to specify the reason why the web process terminated abnormally. + + the web process crashed. + + + the web process exceeded the memory limit. + + + + + + Asynchronously get the raw data for @resource. + +When the operation is finished, @callback will be called. You can then call +webkit_web_resource_get_data_finish() to get the result of the operation. + + + + + + + a #WebKitWebResource + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_web_resource_get_data(). + + + a + string with the data of @resource, or %NULL in case of error. if @length + is not %NULL, the size of the data will be assigned to it. + + + + + + + a #WebKitWebResource + + + + a #GAsyncResult + + + + return location for the length of the resource data + + + + + + Retrieves the #WebKitURIResponse of the resource load operation. +This method returns %NULL if called before the response +is received from the server. You can connect to notify::response +signal to be notified when the response is received. + + + the #WebKitURIResponse, or %NULL if + the response hasn't been received yet. + + + + + a #WebKitWebResource + + + + + + Returns the current active URI of @resource. The active URI might change during +a load operation: + +<orderedlist> +<listitem><para> + When the resource load starts, the active URI is the requested URI +</para></listitem> +<listitem><para> + When the initial request is sent to the server, #WebKitWebResource::sent-request + signal is emitted without a redirected response, the active URI is the URI of + the request sent to the server. +</para></listitem> +<listitem><para> + In case of a server redirection, #WebKitWebResource::sent-request signal + is emitted again with a redirected response, the active URI is the URI the request + was redirected to. +</para></listitem> +<listitem><para> + When the response is received from the server, the active URI is the final + one and it will not change again. +</para></listitem> +</orderedlist> + +You can monitor the active URI by connecting to the notify::uri +signal of @resource. + + + the current active URI of @resource + + + + + a #WebKitWebResource + + + + + + The #WebKitURIResponse associated with this resource. + + + + The current active URI of the #WebKitWebResource. +See webkit_web_resource_get_uri() for more details. + + + + + + + + + + This signal is emitted when an error occurs during the resource +load operation. + + + + + + the #GError that was triggered + + + + + + This signal is emitted when a TLS error occurs during the resource load operation. + + + + + + a #GTlsCertificate + + + + a #GTlsCertificateFlags with the verification status of @certificate + + + + + + This signal is emitted when the resource load finishes successfully +or due to an error. In case of errors #WebKitWebResource::failed signal +is emitted before this one. + + + + + + This signal is emitted after response is received, +every time new data has been received. It's +useful to know the progress of the resource load operation. + + + + + + the length of data received in bytes + + + + + + This signal is emitted when @request has been sent to the +server. In case of a server redirection this signal is +emitted again with the @request argument containing the new +request sent to the server due to the redirection and the +@redirected_response parameter containing the response +received by the server for the initial request. + + + + + + a #WebKitURIRequest + + + + a #WebKitURIResponse, or %NULL + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #WebKitWebView with the default #WebKitWebContext and +no #WebKitUserContentManager associated with it. +See also webkit_web_view_new_with_context(), +webkit_web_view_new_with_user_content_manager(), and +webkit_web_view_new_with_settings(). + + + The newly created #WebKitWebView widget + + + + + Creates a new #WebKitWebView with the given #WebKitWebContext and +no #WebKitUserContentManager associated with it. +See also webkit_web_view_new_with_user_content_manager() and +webkit_web_view_new_with_settings(). + + + The newly created #WebKitWebView widget + + + + + the #WebKitWebContext to be used by the #WebKitWebView + + + + + + Creates a new #WebKitWebView sharing the same web process with @web_view. +This method doesn't have any effect when %WEBKIT_PROCESS_MODEL_SHARED_SECONDARY_PROCESS +process model is used, because a single web process is shared for all the web views in the +same #WebKitWebContext. When using %WEBKIT_PROCESS_MODEL_MULTIPLE_SECONDARY_PROCESSES process model, +this method should always be used when creating the #WebKitWebView in the #WebKitWebView::create signal. +You can also use this method to implement other process models based on %WEBKIT_PROCESS_MODEL_MULTIPLE_SECONDARY_PROCESSES, +like for example, sharing the same web process for all the views in the same security domain. + +The newly created #WebKitWebView will also have the same #WebKitUserContentManager +and #WebKitSettings as @web_view. + + + The newly created #WebKitWebView widget + + + + + the related #WebKitWebView + + + + + + Creates a new #WebKitWebView with the given #WebKitSettings. +See also webkit_web_view_new_with_context(), and +webkit_web_view_new_with_user_content_manager(). + + + The newly created #WebKitWebView widget + + + + + a #WebKitSettings + + + + + + Creates a new #WebKitWebView with the given #WebKitUserContentManager. +The content loaded in the view may be affected by the content injected +in the view by the user content manager. + + + The newly created #WebKitWebView widget + + + + + a #WebKitUserContentManager. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Asynchronously check if it is possible to execute the given editing command. + +When the operation is finished, @callback will be called. You can then call +webkit_web_view_can_execute_editing_command_finish() to get the result of the operation. + + + + + + + a #WebKitWebView + + + + the command to check + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_web_view_can_execute_editing_command(). + + + %TRUE if the editing command can be executed or %FALSE otherwise + + + + + a #WebKitWebView + + + + a #GAsyncResult + + + + + + Determines whether @web_view has a previous history item. + + + %TRUE if able to move back or %FALSE otherwise. + + + + + a #WebKitWebView + + + + + + Determines whether @web_view has a next history item. + + + %TRUE if able to move forward or %FALSE otherwise. + + + + + a #WebKitWebView + + + + + + Whether or not a MIME type can be displayed in @web_view. + + + %TRUE if the MIME type @mime_type can be displayed or %FALSE otherwise + + + + + a #WebKitWebView + + + + a MIME type + + + + + + Requests downloading of the specified URI string for @web_view. + + + a new #WebKitDownload representing + the download operation. + + + + + a #WebKitWebView + + + + the URI to download + + + + + + Request to execute the given @command for @web_view. You can use +webkit_web_view_can_execute_editing_command() to check whether +it's possible to execute the command. + + + + + + + a #WebKitWebView + + + + the command to execute + + + + + + Request to execute the given @command with @argument for @web_view. You can use +webkit_web_view_can_execute_editing_command() to check whether +it's possible to execute the command. + + + + + + + a #WebKitWebView + + + + the command to execute + + + + the command argument + + + + + + Obtains the #WebKitBackForwardList associated with the given #WebKitWebView. The +#WebKitBackForwardList is owned by the #WebKitWebView. + + + the #WebKitBackForwardList + + + + + a #WebKitWebView + + + + + + Gets the color that is used to draw the @web_view background before +the actual contents are rendered. +For more information see also webkit_web_view_set_background_color() + + + + + + + a #WebKitWebView + + + + a #GdkRGBA to fill in with the background color + + + + + + Gets the web context of @web_view. + + + the #WebKitWebContext of the view + + + + + a #WebKitWebView + + + + + + Returns the current custom character encoding name of @web_view. + + + the current custom character encoding name or %NULL if no + custom character encoding has been set. + + + + + a #WebKitWebView + + + + + + Gets the web editor state of @web_view. + + + the #WebKitEditorState of the view + + + + + a #WebKitWebView + + + + + + Gets the value of the #WebKitWebView:estimated-load-progress property. +You can monitor the estimated progress of a load operation by +connecting to the notify::estimated-load-progress signal of @web_view. + + + an estimate of the of the percent complete for a document + load as a range from 0.0 to 1.0. + + + + + a #WebKitWebView + + + + + + Returns favicon currently associated to @web_view, if any. You can +connect to notify::favicon signal of @web_view to be notified when +the favicon is available. + + + a pointer to a #cairo_surface_t with the + favicon or %NULL if there's no icon associated with @web_view. + + + + + a #WebKitWebView + + + + + + Gets the #WebKitFindController that will allow the caller to query +the #WebKitWebView for the text to look for. + + + the #WebKitFindController associated to +this particular #WebKitWebView. + + + + + the #WebKitWebView + + + + + + Get the #WebKitWebInspector associated to @web_view + + + the #WebKitWebInspector of @web_view + + + + + a #WebKitWebView + + + + + + Get the global JavaScript context used by @web_view to deserialize the +result values of scripts executed with webkit_web_view_run_javascript(). + Use jsc_value_get_context() instead. + + + the <function>JSGlobalContextRef</function> used by @web_view to deserialize + the result values of scripts. + + + + + a #WebKitWebView + + + + + + Return the main resource of @web_view. + + + the main #WebKitWebResource of the view + or %NULL if nothing has been loaded. + + + + + a #WebKitWebView + + + + + + Get the identifier of the #WebKitWebPage corresponding to +the #WebKitWebView + + + the page ID of @web_view. + + + + + a #WebKitWebView + + + + + + Gets the current session state of @web_view + + + a #WebKitWebViewSessionState + + + + + a #WebKitWebView + + + + + + Gets the #WebKitSettings currently applied to @web_view. +If no other #WebKitSettings have been explicitly applied to +@web_view with webkit_web_view_set_settings(), the default +#WebKitSettings will be returned. This method always returns +a valid #WebKitSettings object. +To modify any of the @web_view settings, you can either create +a new #WebKitSettings object with webkit_settings_new(), setting +the desired preferences, and then replace the existing @web_view +settings with webkit_web_view_set_settings() or get the existing +@web_view settings and update it directly. #WebKitSettings objects +can be shared by multiple #WebKitWebView<!-- -->s, so modifying +the settings of a #WebKitWebView would affect other +#WebKitWebView<!-- -->s using the same #WebKitSettings. + + + the #WebKitSettings attached to @web_view + + + + + a #WebKitWebView + + + + + + Asynchronously retrieves a snapshot of @web_view for @region. +@options specifies how the snapshot should be rendered. + +When the operation is finished, @callback will be called. You must +call webkit_web_view_get_snapshot_finish() to get the result of the +operation. + + + + + + + a #WebKitWebView + + + + the #WebKitSnapshotRegion for this snapshot + + + + #WebKitSnapshotOptions for the snapshot + + + + a #GCancellable + + + + a #GAsyncReadyCallback + + + + user data + + + + + + Finishes an asynchronous operation started with webkit_web_view_get_snapshot(). + + + a #cairo_surface_t with the retrieved snapshot or %NULL in error. + + + + + a #WebKitWebView + + + + a #GAsyncResult + + + + + + Gets the value of the #WebKitWebView:title property. +You can connect to notify::title signal of @web_view to +be notified when the title has been received. + + + The main frame document title of @web_view. + + + + + a #WebKitWebView + + + + + + Retrieves the #GTlsCertificate associated with the main resource of @web_view, +and the #GTlsCertificateFlags showing what problems, if any, have been found +with that certificate. +If the connection is not HTTPS, this function returns %FALSE. +This function should be called after a response has been received from the +server, so you can connect to #WebKitWebView::load-changed and call this function +when it's emitted with %WEBKIT_LOAD_COMMITTED event. + +Note that this function provides no information about the security of the web +page if the current #WebKitTLSErrorsPolicy is @WEBKIT_TLS_ERRORS_POLICY_IGNORE, +as subresources of the page may be controlled by an attacker. This function +may safely be used to determine the security status of the current page only +if the current #WebKitTLSErrorsPolicy is @WEBKIT_TLS_ERRORS_POLICY_FAIL, in +which case subresources that fail certificate verification will be blocked. + + + %TRUE if the @web_view connection uses HTTPS and a response has been received + from the server, or %FALSE otherwise. + + + + + a #WebKitWebView + + + + return location for a #GTlsCertificate + + + + return location for a #GTlsCertificateFlags the verification status of @certificate + + + + + + Returns the current active URI of @web_view. The active URI might change during +a load operation: + +<orderedlist> +<listitem><para> + When nothing has been loaded yet on @web_view the active URI is %NULL. +</para></listitem> +<listitem><para> + When a new load operation starts the active URI is the requested URI: + <itemizedlist> + <listitem><para> + If the load operation was started by webkit_web_view_load_uri(), + the requested URI is the given one. + </para></listitem> + <listitem><para> + If the load operation was started by webkit_web_view_load_html(), + the requested URI is "about:blank". + </para></listitem> + <listitem><para> + If the load operation was started by webkit_web_view_load_alternate_html(), + the requested URI is content URI provided. + </para></listitem> + <listitem><para> + If the load operation was started by webkit_web_view_go_back() or + webkit_web_view_go_forward(), the requested URI is the original URI + of the previous/next item in the #WebKitBackForwardList of @web_view. + </para></listitem> + <listitem><para> + If the load operation was started by + webkit_web_view_go_to_back_forward_list_item(), the requested URI + is the opriginal URI of the given #WebKitBackForwardListItem. + </para></listitem> + </itemizedlist> +</para></listitem> +<listitem><para> + If there is a server redirection during the load operation, + the active URI is the redirected URI. When the signal + #WebKitWebView::load-changed is emitted with %WEBKIT_LOAD_REDIRECTED + event, the active URI is already updated to the redirected URI. +</para></listitem> +<listitem><para> + When the signal #WebKitWebView::load-changed is emitted + with %WEBKIT_LOAD_COMMITTED event, the active URI is the final + one and it will not change unless a new load operation is started + or a navigation action within the same page is performed. +</para></listitem> +</orderedlist> + +You can monitor the active URI by connecting to the notify::uri +signal of @web_view. + + + the current active URI of @web_view or %NULL + if nothing has been loaded yet. + + + + + a #WebKitWebView + + + + + + Gets the user content manager associated to @web_view. + + + the #WebKitUserContentManager associated with the view + + + + + a #WebKitWebView + + + + + + Get the #WebKitWebsiteDataManager associated to @web_view. If @web_view is not ephemeral, +the returned #WebKitWebsiteDataManager will be the same as the #WebKitWebsiteDataManager +of @web_view's #WebKitWebContext. + + + a #WebKitWebsiteDataManager + + + + + a #WebKitWebView + + + + + + Get the #WebKitWindowProperties object containing the properties +that the window containing @web_view should have. + + + the #WebKitWindowProperties of @web_view + + + + + a #WebKitWebView + + + + + + Get the zoom level of @web_view, i.e. the factor by which the +view contents are scaled with respect to their original size. + + + the current zoom level of @web_view + + + + + a #WebKitWebView + + + + + + Loads the previous history item. +You can monitor the load operation by connecting to +#WebKitWebView::load-changed signal. + + + + + + + a #WebKitWebView + + + + + + Loads the next history item. +You can monitor the load operation by connecting to +#WebKitWebView::load-changed signal. + + + + + + + a #WebKitWebView + + + + + + Loads the specific history item @list_item. +You can monitor the load operation by connecting to +#WebKitWebView::load-changed signal. + + + + + + + a #WebKitWebView + + + + a #WebKitBackForwardListItem + + + + + + Get whether a #WebKitWebView was created with #WebKitWebView:is-controlled-by-automation +property enabled. Only #WebKitWebView<!-- -->s controlled by automation can be used in an +automation session. + + + %TRUE if @web_view is controlled by automation, or %FALSE otherwise. + + + + + a #WebKitWebView + + + + + + + + + + + + + + + + + Get whether a #WebKitWebView is ephemeral. To create an ephemeral #WebKitWebView you need to +use g_object_new() and pass is-ephemeral property with %TRUE value. See +#WebKitWebView:is-ephemeral for more details. +If @web_view was created with a ephemeral #WebKitWebView:related-view or an +ephemeral #WebKitWebView:web-context it will also be ephemeral. + + + %TRUE if @web_view is ephemeral or %FALSE otherwise. + + + + + a #WebKitWebView + + + + + + Gets the value of the #WebKitWebView:is-loading property. +You can monitor when a #WebKitWebView is loading a page by connecting to +notify::is-loading signal of @web_view. This is useful when you are +interesting in knowing when the view is loading something but not in the +details about the status of the load operation, for example to start a spinner +when the view is loading a page and stop it when it finishes. + + + %TRUE if @web_view is loading a page or %FALSE otherwise. + + + + + a #WebKitWebView + + + + + + Gets the value of the #WebKitWebView:is-playing-audio property. +You can monitor when a page in a #WebKitWebView is playing audio by +connecting to the notify::is-playing-audio signal of @web_view. This +is useful when the application wants to provide visual feedback when a +page is producing sound. + + + %TRUE if a page in @web_view is playing audio or %FALSE otherwise. + + + + + a #WebKitWebView + + + + + + Load the given @content string for the URI @content_uri. +This allows clients to display page-loading errors in the #WebKitWebView itself. +When this method is called from #WebKitWebView::load-failed signal to show an +error page, then the back-forward list is maintained appropriately. +For everything else this method works the same way as webkit_web_view_load_html(). + + + + + + + a #WebKitWebView + + + + the new content to display as the main page of the @web_view + + + + the URI for the alternate page content + + + + the base URI for relative locations or %NULL + + + + + + Load the specified @bytes into @web_view using the given @mime_type and @encoding. +When @mime_type is %NULL, it defaults to "text/html". +When @encoding is %NULL, it defaults to "UTF-8". +When @base_uri is %NULL, it defaults to "about:blank". +You can monitor the load operation by connecting to #WebKitWebView::load-changed signal. + + + + + + + a #WebKitWebView + + + + input data to load + + + + the MIME type of @bytes, or %NULL + + + + the character encoding of @bytes, or %NULL + + + + the base URI for relative locations or %NULL + + + + + + Load the given @content string with the specified @base_uri. +If @base_uri is not %NULL, relative URLs in the @content will be +resolved against @base_uri and absolute local paths must be children of the @base_uri. +For security reasons absolute local paths that are not children of @base_uri +will cause the web process to terminate. +If you need to include URLs in @content that are local paths in a different +directory than @base_uri you can build a data URI for them. When @base_uri is %NULL, +it defaults to "about:blank". The mime type of the document will be "text/html". +You can monitor the load operation by connecting to #WebKitWebView::load-changed signal. + + + + + + + a #WebKitWebView + + + + The HTML string to load + + + + The base URI for relative locations or %NULL + + + + + + Load the specified @plain_text string into @web_view. The mime type of +document will be "text/plain". You can monitor the load +operation by connecting to #WebKitWebView::load-changed signal. + + + + + + + a #WebKitWebView + + + + The plain text to load + + + + + + Requests loading of the specified #WebKitURIRequest. +You can monitor the load operation by connecting to +#WebKitWebView::load-changed signal. + + + + + + + a #WebKitWebView + + + + a #WebKitURIRequest to load + + + + + + Requests loading of the specified URI string. +You can monitor the load operation by connecting to +#WebKitWebView::load-changed signal. + + + + + + + a #WebKitWebView + + + + an URI string + + + + + + Reloads the current contents of @web_view. +See also webkit_web_view_reload_bypass_cache(). + + + + + + + a #WebKitWebView + + + + + + Reloads the current contents of @web_view without +using any cached data. + + + + + + + a #WebKitWebView + + + + + + Restore the @web_view session state from @state + + + + + + + a #WebKitWebView + + + + a #WebKitWebViewSessionState + + + + + + Asynchronously run @script in the context of the current page in @web_view. If +WebKitSettings:enable-javascript is FALSE, this method will do nothing. + +When the operation is finished, @callback will be called. You can then call +webkit_web_view_run_javascript_finish() to get the result of the operation. + + + + + + + a #WebKitWebView + + + + the script to run + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the script finished + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_web_view_run_javascript(). + +This is an example of using webkit_web_view_run_javascript() with a script returning +a string: + +<informalexample><programlisting> +static void +web_view_javascript_finished (GObject *object, + GAsyncResult *result, + gpointer user_data) +{ + WebKitJavascriptResult *js_result; + JSCValue *value; + GError *error = NULL; + + js_result = webkit_web_view_run_javascript_finish (WEBKIT_WEB_VIEW (object), result, &error); + if (!js_result) { + g_warning ("Error running javascript: %s", error->message); + g_error_free (error); + return; + } + + value = webkit_javascript_result_get_js_value (js_result); + if (jsc_value_is_string (value)) { + JSCException *exception; + gchar *str_value; + + str_value = jsc_value_to_string (value); + exception = jsc_context_get_exception (jsc_value_get_context (value)); + if (exception) + g_warning ("Error running javascript: %s", jsc_exception_get_message (exception)); + else + g_print ("Script result: %s\n", str_value); + g_free (str_value); + } else { + g_warning ("Error running javascript: unexpected return value"); + } + webkit_javascript_result_unref (js_result); +} + +static void +web_view_get_link_url (WebKitWebView *web_view, + const gchar *link_id) +{ + gchar *script; + + script = g_strdup_printf ("window.document.getElementById('%s').href;", link_id); + webkit_web_view_run_javascript (web_view, script, NULL, web_view_javascript_finished, NULL); + g_free (script); +} +</programlisting></informalexample> + + + a #WebKitJavascriptResult with the result of the last executed statement in @script + or %NULL in case of error + + + + + a #WebKitWebView + + + + a #GAsyncResult + + + + + + Asynchronously run the script from @resource in the context of the +current page in @web_view. + +When the operation is finished, @callback will be called. You can +then call webkit_web_view_run_javascript_from_gresource_finish() to get the result +of the operation. + + + + + + + a #WebKitWebView + + + + the location of the resource to load + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the script finished + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_web_view_run_javascript_from_gresource(). + +Check webkit_web_view_run_javascript_finish() for a usage example. + + + a #WebKitJavascriptResult with the result of the last executed statement in @script + or %NULL in case of error + + + + + a #WebKitWebView + + + + a #GAsyncResult + + + + + + Asynchronously run @script in the script world with name @world_name of the current page context in @web_view. +If WebKitSettings:enable-javascript is FALSE, this method will do nothing. + +When the operation is finished, @callback will be called. You can then call +webkit_web_view_run_javascript_in_world_finish() to get the result of the operation. + + + + + + + a #WebKitWebView + + + + the script to run + + + + the name of a #WebKitScriptWorld + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the script finished + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_web_view_run_javascript_in_world(). + + + a #WebKitJavascriptResult with the result of the last executed statement in @script + or %NULL in case of error + + + + + a #WebKitWebView + + + + a #GAsyncResult + + + + + + Asynchronously save the current web page associated to the +#WebKitWebView into a self-contained format using the mode +specified in @save_mode. + +When the operation is finished, @callback will be called. You can +then call webkit_web_view_save_finish() to get the result of the +operation. + + + + + + + a #WebKitWebView + + + + the #WebKitSaveMode specifying how the web page should be saved. + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_web_view_save(). + + + a #GInputStream with the result of saving + the current web page or %NULL in case of error. + + + + + a #WebKitWebView + + + + a #GAsyncResult + + + + + + Asynchronously save the current web page associated to the +#WebKitWebView into a self-contained format using the mode +specified in @save_mode and writing it to @file. + +When the operation is finished, @callback will be called. You can +then call webkit_web_view_save_to_file_finish() to get the result of the +operation. + + + + + + + a #WebKitWebView + + + + the #GFile where the current web page should be saved to. + + + + the #WebKitSaveMode specifying how the web page should be saved. + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_web_view_save_to_file(). + + + %TRUE if the web page was successfully saved to a file or %FALSE otherwise. + + + + + a #WebKitWebView + + + + a #GAsyncResult + + + + + + Sets the color that will be used to draw the @web_view background before +the actual contents are rendered. Note that if the web page loaded in @web_view +specifies a background color, it will take precedence over the @rgba color. +By default the @web_view background color is opaque white. +Note that the parent window must have a RGBA visual and +#GtkWidget:app-paintable property set to %TRUE for backgrounds colors to work. + +<informalexample><programlisting> +static void browser_window_set_background_color (BrowserWindow *window, + const GdkRGBA *rgba) +{ + WebKitWebView *web_view; + GdkScreen *screen = gtk_window_get_screen (GTK_WINDOW (window)); + GdkVisual *rgba_visual = gdk_screen_get_rgba_visual (screen); + + if (!rgba_visual) + return; + + gtk_widget_set_visual (GTK_WIDGET (window), rgba_visual); + gtk_widget_set_app_paintable (GTK_WIDGET (window), TRUE); + + web_view = browser_window_get_web_view (window); + webkit_web_view_set_background_color (web_view, rgba); +} +</programlisting></informalexample> + + + + + + + a #WebKitWebView + + + + a #GdkRGBA + + + + + + Sets the current custom character encoding override of @web_view. The custom +character encoding will override any text encoding detected via HTTP headers or +META tags. Calling this method will stop any current load operation and reload the +current page. Setting the custom character encoding to %NULL removes the character +encoding override. + + + + + + + a #WebKitWebView + + + + a character encoding name or %NULL + + + + + + Sets whether the user is allowed to edit the HTML document. + +If @editable is %TRUE, @web_view allows the user to edit the HTML document. If +@editable is %FALSE, an element in @web_view's document can only be edited if the +CONTENTEDITABLE attribute has been set on the element or one of its parent +elements. By default a #WebKitWebView is not editable. + +Normally, a HTML document is not editable unless the elements within the +document are editable. This function provides a way to make the contents +of a #WebKitWebView editable without altering the document or DOM structure. + + + + + + + a #WebKitWebView + + + + a #gboolean indicating the editable state + + + + + + Sets the #WebKitSettings to be applied to @web_view. The +existing #WebKitSettings of @web_view will be replaced by +@settings. New settings are applied immediately on @web_view. +The same #WebKitSettings object can be shared +by multiple #WebKitWebView<!-- -->s. + + + + + + + a #WebKitWebView + + + + a #WebKitSettings + + + + + + Set the zoom level of @web_view, i.e. the factor by which the +view contents are scaled with respect to their original size. + + + + + + + a #WebKitWebView + + + + the zoom level + + + + + + Stops any ongoing loading operation in @web_view. +This method does nothing if no content is being loaded. +If there is a loading operation in progress, it will be cancelled and +#WebKitWebView::load-failed signal will be emitted with +%WEBKIT_NETWORK_ERROR_CANCELLED error. + + + + + + + a #WebKitWebView + + + + + + Tries to close the @web_view. This will fire the onbeforeunload event +to ask the user for confirmation to close the page. If there isn't an +onbeforeunload event handler or the user confirms to close the page, +the #WebKitWebView::close signal is emitted, otherwise nothing happens. + + + + + + + a #WebKitWebView + + + + + + Whether the pages loaded inside #WebKitWebView are editable. For more +information see webkit_web_view_set_editable(). + + + + An estimate of the percent completion for the current loading operation. +This value will range from 0.0 to 1.0 and, once a load completes, +will remain at 1.0 until a new load starts, at which point it +will be reset to 0.0. +The value is an estimate based on the total number of bytes expected +to be received for a document, including all its possible subresources +and child documents. + + + + The favicon currently associated to the #WebKitWebView. +See webkit_web_view_get_favicon() for more details. + + + + Whether the #WebKitWebView is controlled by automation. This should only be used when +creating a new #WebKitWebView as a response to #WebKitAutomationSession::create-web-view +signal request. + + + + Whether the #WebKitWebView is ephemeral. An ephemeral web view never writes +website data to the client storage, no matter what #WebKitWebsiteDataManager +its context is using. This is normally used to implement private browsing mode. +This is a %G_PARAM_CONSTRUCT_ONLY property, so you have to create a ephemeral +#WebKitWebView and it can't be changed. Note that all #WebKitWebView<!-- -->s +created with an ephemeral #WebKitWebContext will be ephemeral automatically. +See also webkit_web_context_new_ephemeral(). + + + + Whether the #WebKitWebView is currently loading a page. This property becomes +%TRUE as soon as a new load operation is requested and before the +#WebKitWebView::load-changed signal is emitted with %WEBKIT_LOAD_STARTED and +at that point the active URI is the requested one. +When the load operation finishes the property is set to %FALSE before +#WebKitWebView::load-changed is emitted with %WEBKIT_LOAD_FINISHED. + + + + Whether the #WebKitWebView is currently playing audio from a page. +This property becomes %TRUE as soon as web content starts playing any +kind of audio. When a page is no longer playing any kind of sound, +the property is set back to %FALSE. + + + + The related #WebKitWebView used when creating the view to share the +same web process. This property is not readable because the related +web view is only valid during the object construction. + + + + The #WebKitSettings of the view. + + + + The main frame document title of this #WebKitWebView. If +the title has not been received yet, it will be %NULL. + + + + The current active URI of the #WebKitWebView. +See webkit_web_view_get_uri() for more details. + + + + The #WebKitUserContentManager of the view. + + + + The #WebKitWebContext of the view. + + + + The zoom level of the #WebKitWebView content. +See webkit_web_view_set_zoom_level() for more details. + + + + + + + + + + This signal is emitted when the user is challenged with HTTP +authentication. To let the application access or supply +the credentials as well as to allow the client application +to either cancel the request or perform the authentication, +the signal will pass an instance of the +#WebKitAuthenticationRequest in the @request argument. +To handle this signal asynchronously you should keep a ref +of the request and return %TRUE. To disable HTTP authentication +entirely, connect to this signal and simply return %TRUE. + +The default signal handler will run a default authentication +dialog asynchronously for the user to interact with. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + a #WebKitAuthenticationRequest + + + + + + Emitted when closing a #WebKitWebView is requested. This occurs when a +call is made from JavaScript's <function>window.close</function> function or +after trying to close the @web_view with webkit_web_view_try_close(). +It is the owner's responsibility to handle this signal to hide or +destroy the #WebKitWebView, if necessary. + + + + + + Emitted when a context menu is about to be displayed to give the application +a chance to customize the proposed menu, prevent the menu from being displayed, +or build its own context menu. +<itemizedlist> +<listitem><para> + To customize the proposed menu you can use webkit_context_menu_prepend(), + webkit_context_menu_append() or webkit_context_menu_insert() to add new + #WebKitContextMenuItem<!-- -->s to @context_menu, webkit_context_menu_move_item() + to reorder existing items, or webkit_context_menu_remove() to remove an + existing item. The signal handler should return %FALSE, and the menu represented + by @context_menu will be shown. +</para></listitem> +<listitem><para> + To prevent the menu from being displayed you can just connect to this signal + and return %TRUE so that the proposed menu will not be shown. +</para></listitem> +<listitem><para> + To build your own menu, you can remove all items from the proposed menu with + webkit_context_menu_remove_all(), add your own items and return %FALSE so + that the menu will be shown. You can also ignore the proposed #WebKitContextMenu, + build your own #GtkMenu and return %TRUE to prevent the proposed menu from being shown. +</para></listitem> +<listitem><para> + If you just want the default menu to be shown always, simply don't connect to this + signal because showing the proposed context menu is the default behaviour. +</para></listitem> +</itemizedlist> + +The @event is expected to be one of the following types: +<itemizedlist> +<listitem><para> +a #GdkEventButton of type %GDK_BUTTON_PRESS when the context menu +was triggered with mouse. +</para></listitem> +<listitem><para> +a #GdkEventKey of type %GDK_KEY_PRESS if the keyboard was used to show +the menu. +</para></listitem> +<listitem><para> +a generic #GdkEvent of type %GDK_NOTHING when the #GtkWidget::popup-menu +signal was used to show the context menu. +</para></listitem> +</itemizedlist> + +If the signal handler returns %FALSE the context menu represented by @context_menu +will be shown, if it return %TRUE the context menu will not be shown. + +The proposed #WebKitContextMenu passed in @context_menu argument is only valid +during the signal emission. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the proposed #WebKitContextMenu + + + + the #GdkEvent that triggered the context menu + + + + a #WebKitHitTestResult + + + + + + Emitted after #WebKitWebView::context-menu signal, if the context menu is shown, +to notify that the context menu is dismissed. + + + + + + Emitted when the creation of a new #WebKitWebView is requested. +If this signal is handled the signal handler should return the +newly created #WebKitWebView. + +The #WebKitNavigationAction parameter contains information about the +navigation action that triggered this signal. + +When using %WEBKIT_PROCESS_MODEL_MULTIPLE_SECONDARY_PROCESSES +process model, the new #WebKitWebView should be related to +@web_view to share the same web process, see webkit_web_view_new_with_related_view() +for more details. + +The new #WebKitWebView should not be displayed to the user +until the #WebKitWebView::ready-to-show signal is emitted. + + a newly allocated #WebKitWebView widget + or %NULL to propagate the event further. + + + + + a #WebKitNavigationAction + + + + + + This signal is emitted when WebKit is requesting the client to decide a policy +decision, such as whether to navigate to a page, open a new window or whether or +not to download a resource. The #WebKitNavigationPolicyDecision passed in the +@decision argument is a generic type, but should be casted to a more +specific type when making the decision. For example: + +<informalexample><programlisting> +static gboolean +decide_policy_cb (WebKitWebView *web_view, + WebKitPolicyDecision *decision, + WebKitPolicyDecisionType type) +{ + switch (type) { + case WEBKIT_POLICY_DECISION_TYPE_NAVIGATION_ACTION: { + WebKitNavigationPolicyDecision *navigation_decision = WEBKIT_NAVIGATION_POLICY_DECISION (decision); + /<!-- -->* Make a policy decision here. *<!-- -->/ + break; + } + case WEBKIT_POLICY_DECISION_TYPE_NEW_WINDOW_ACTION: { + WebKitNavigationPolicyDecision *navigation_decision = WEBKIT_NAVIGATION_POLICY_DECISION (decision); + /<!-- -->* Make a policy decision here. *<!-- -->/ + break; + } + case WEBKIT_POLICY_DECISION_TYPE_RESPONSE: + WebKitResponsePolicyDecision *response = WEBKIT_RESPONSE_POLICY_DECISION (decision); + /<!-- -->* Make a policy decision here. *<!-- -->/ + break; + default: + /<!-- -->* Making no decision results in webkit_policy_decision_use(). *<!-- -->/ + return FALSE; + } + return TRUE; +} +</programlisting></informalexample> + +It is possible to make policy decision asynchronously, by simply calling g_object_ref() +on the @decision argument and returning %TRUE to block the default signal handler. +If the last reference is removed on a #WebKitPolicyDecision and no decision has been +made explicitly, webkit_policy_decision_use() will be the default policy decision. The +default signal handler will simply call webkit_policy_decision_use(). Only the first +policy decision chosen for a given #WebKitPolicyDecision will have any affect. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the #WebKitPolicyDecision + + + + a #WebKitPolicyDecisionType denoting the type of @decision + + + + + + Emitted when JavaScript code calls +<function>element.webkitRequestFullScreen</function>. If the +signal is not handled the #WebKitWebView will proceed to full screen +its top level window. This signal can be used by client code to +request permission to the user prior doing the full screen +transition and eventually prepare the top-level window +(e.g. hide some widgets that would otherwise be part of the +full screen window). + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to continue emission of the event. + + + + + This signal is emitted when insecure content has been detected +in a page loaded through a secure connection. This typically +means that a external resource from an unstrusted source has +been run or displayed, resulting in a mix of HTTPS and +non-HTTPS content. + +You can check the @event parameter to know exactly which kind +of event has been detected (see #WebKitInsecureContentEvent). + + + + + + the #WebKitInsecureContentEvent + + + + + + Emitted when the #WebKitWebView is about to restore its top level +window out of its full screen state. This signal can be used by +client code to restore widgets hidden during the +#WebKitWebView::enter-fullscreen stage for instance. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to continue emission of the event. + + + + + Emitted when a load operation in @web_view changes. +The signal is always emitted with %WEBKIT_LOAD_STARTED when a +new load request is made and %WEBKIT_LOAD_FINISHED when the load +finishes successfully or due to an error. When the ongoing load +operation fails #WebKitWebView::load-failed signal is emitted +before #WebKitWebView::load-changed is emitted with +%WEBKIT_LOAD_FINISHED. +If a redirection is received from the server, this signal is emitted +with %WEBKIT_LOAD_REDIRECTED after the initial emission with +%WEBKIT_LOAD_STARTED and before %WEBKIT_LOAD_COMMITTED. +When the page content starts arriving the signal is emitted with +%WEBKIT_LOAD_COMMITTED event. + +You can handle this signal and use a switch to track any ongoing +load operation. + +<informalexample><programlisting> +static void web_view_load_changed (WebKitWebView *web_view, + WebKitLoadEvent load_event, + gpointer user_data) +{ + switch (load_event) { + case WEBKIT_LOAD_STARTED: + /<!-- -->* New load, we have now a provisional URI *<!-- -->/ + provisional_uri = webkit_web_view_get_uri (web_view); + /<!-- -->* Here we could start a spinner or update the + <!-- -->* location bar with the provisional URI *<!-- -->/ + break; + case WEBKIT_LOAD_REDIRECTED: + redirected_uri = webkit_web_view_get_uri (web_view); + break; + case WEBKIT_LOAD_COMMITTED: + /<!-- -->* The load is being performed. Current URI is + <!-- -->* the final one and it won't change unless a new + <!-- -->* load is requested or a navigation within the + <!-- -->* same page is performed *<!-- -->/ + uri = webkit_web_view_get_uri (web_view); + break; + case WEBKIT_LOAD_FINISHED: + /<!-- -->* Load finished, we can now stop the spinner *<!-- -->/ + break; + } +} +</programlisting></informalexample> + + + + + + the #WebKitLoadEvent + + + + + + Emitted when an error occurs during a load operation. +If the error happened when starting to load data for a page +@load_event will be %WEBKIT_LOAD_STARTED. If it happened while +loading a committed data source @load_event will be %WEBKIT_LOAD_COMMITTED. +Since a load error causes the load operation to finish, the signal +WebKitWebView::load-changed will always be emitted with +%WEBKIT_LOAD_FINISHED event right after this one. + +By default, if the signal is not handled, a stock error page will be displayed. +You need to handle the signal if you want to provide your own error page. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the #WebKitLoadEvent of the load operation + + + + the URI that failed to load + + + + the #GError that was triggered + + + + + + Emitted when a TLS error occurs during a load operation. +To allow an exception for this @certificate +and the host of @failing_uri use webkit_web_context_allow_tls_certificate_for_host(). + +To handle this signal asynchronously you should call g_object_ref() on @certificate +and return %TRUE. + +If %FALSE is returned, #WebKitWebView::load-failed will be emitted. The load +will finish regardless of the returned value. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the URI that failed to load + + + + a #GTlsCertificate + + + + a #GTlsCertificateFlags with the verification status of @certificate + + + + + + This signal is emitted when the mouse cursor moves over an +element such as a link, image or a media element. To determine +what type of element the mouse cursor is over, a Hit Test is performed +on the current mouse coordinates and the result is passed in the +@hit_test_result argument. The @modifiers argument is a bitmask of +#GdkModifierType flags indicating the state of modifier keys. +The signal is emitted again when the mouse is moved out of the +current element with a new @hit_test_result. + + + + + + a #WebKitHitTestResult + + + + a bitmask of #GdkModifierType + + + + + + This signal is emitted when WebKit is requesting the client to +decide about a permission request, such as allowing the browser +to switch to fullscreen mode, sharing its location or similar +operations. + +A possible way to use this signal could be through a dialog +allowing the user decide what to do with the request: + +<informalexample><programlisting> +static gboolean permission_request_cb (WebKitWebView *web_view, + WebKitPermissionRequest *request, + GtkWindow *parent_window) +{ + GtkWidget *dialog = gtk_message_dialog_new (parent_window, + GTK_DIALOG_MODAL, + GTK_MESSAGE_QUESTION, + GTK_BUTTONS_YES_NO, + "Allow Permission Request?"); + gtk_widget_show (dialog); + gint result = gtk_dialog_run (GTK_DIALOG (dialog)); + + switch (result) { + case GTK_RESPONSE_YES: + webkit_permission_request_allow (request); + break; + default: + webkit_permission_request_deny (request); + break; + } + gtk_widget_destroy (dialog); + + return TRUE; +} +</programlisting></informalexample> + +It is possible to handle permission requests asynchronously, by +simply calling g_object_ref() on the @request argument and +returning %TRUE to block the default signal handler. If the +last reference is removed on a #WebKitPermissionRequest and the +request has not been handled, webkit_permission_request_deny() +will be the default action. + +If the signal is not handled, the @request will be completed automatically +by the specific #WebKitPermissionRequest that could allow or deny it. Check the +documentation of classes implementing #WebKitPermissionRequest interface to know +their default action. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the #WebKitPermissionRequest + + + + + + Emitted when printing is requested on @web_view, usually by a JavaScript call, +before the print dialog is shown. This signal can be used to set the initial +print settings and page setup of @print_operation to be used as default values in +the print dialog. You can call webkit_print_operation_set_print_settings() and +webkit_print_operation_set_page_setup() and then return %FALSE to propagate the +event so that the print dialog is shown. + +You can connect to this signal and return %TRUE to cancel the print operation +or implement your own print dialog. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the #WebKitPrintOperation that will handle the print request + + + + + + Emitted after #WebKitWebView::create on the newly created #WebKitWebView +when it should be displayed to the user. When this signal is emitted +all the information about how the window should look, including +size, position, whether the location, status and scrollbars +should be displayed, is already set on the #WebKitWindowProperties +of @web_view. See also webkit_web_view_get_window_properties(). + + + + + + Emitted when a new resource is going to be loaded. The @request parameter +contains the #WebKitURIRequest that will be sent to the server. +You can monitor the load operation by connecting to the different signals +of @resource. + + + + + + a #WebKitWebResource + + + + a #WebKitURIRequest + + + + + + Emitted after #WebKitWebView::ready-to-show on the newly +created #WebKitWebView when JavaScript code calls +<function>window.showModalDialog</function>. The purpose of +this signal is to allow the client application to prepare the +new view to behave as modal. Once the signal is emitted a new +main loop will be run to block user interaction in the parent +#WebKitWebView until the new dialog is closed. + + + + + + This signal is emitted when the user interacts with a &lt;input +type='color' /&gt; HTML element, requesting from WebKit to show +a dialog to select a color. To let the application know the details of +the color chooser, as well as to allow the client application to either +cancel the request or perform an actual color selection, the signal will +pass an instance of the #WebKitColorChooserRequest in the @request +argument. + +It is possible to handle this request asynchronously by increasing the +reference count of the request. + +The default signal handler will asynchronously run a regular +#GtkColorChooser for the user to interact with. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + a #WebKitColorChooserRequest + + + + + + This signal is emitted when the user interacts with a &lt;input +type='file' /&gt; HTML element, requesting from WebKit to show +a dialog to select one or more files to be uploaded. To let the +application know the details of the file chooser, as well as to +allow the client application to either cancel the request or +perform an actual selection of files, the signal will pass an +instance of the #WebKitFileChooserRequest in the @request +argument. + +The default signal handler will asynchronously run a regular +#GtkFileChooserDialog for the user to interact with. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + a #WebKitFileChooserRequest + + + + + + Emitted when JavaScript code calls <function>window.alert</function>, +<function>window.confirm</function> or <function>window.prompt</function>, +or when <function>onbeforeunload</function> event is fired. +The @dialog parameter should be used to build the dialog. +If the signal is not handled a different dialog will be built and shown depending +on the dialog type: +<itemizedlist> +<listitem><para> + %WEBKIT_SCRIPT_DIALOG_ALERT: message dialog with a single Close button. +</para></listitem> +<listitem><para> + %WEBKIT_SCRIPT_DIALOG_CONFIRM: message dialog with OK and Cancel buttons. +</para></listitem> +<listitem><para> + %WEBKIT_SCRIPT_DIALOG_PROMPT: message dialog with OK and Cancel buttons and + a text entry with the default text. +</para></listitem> +<listitem><para> + %WEBKIT_SCRIPT_DIALOG_BEFORE_UNLOAD_CONFIRM: message dialog with Stay and Leave buttons. +</para></listitem> +</itemizedlist> + +It is possible to handle the script dialog request asynchronously, by simply +caling webkit_script_dialog_ref() on the @dialog argument and calling +webkit_script_dialog_close() when done. +If the last reference is removed on a #WebKitScriptDialog and the dialog has not been +closed, webkit_script_dialog_close() will be called. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the #WebKitScriptDialog to show + + + + + + This signal is emitted when a notification should be presented to the +user. The @notification is kept alive until either: 1) the web page cancels it +or 2) a navigation happens. + +The default handler will emit a notification using libnotify, if built with +support for it. + + %TRUE to stop other handlers from being invoked. %FALSE otherwise. + + + + + a #WebKitNotification + + + + + + This signal is emitted when a select element in @web_view needs to display a +dropdown menu. This signal can be used to show a custom menu, using @menu to get +the details of all items that should be displayed. The area of the element in the +#WebKitWebView is given as @rectangle parameter, it can be used to position the +menu. If this was triggered by a user interaction, like a mouse click, +@event parameter provides the #GdkEvent. +To handle this signal asynchronously you should keep a ref of the @menu. + +The default signal handler will pop up a #GtkMenu. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + the #WebKitOptionMenu + + + + the #GdkEvent that triggered the menu, or %NULL + + + + the option element area + + + + + + This signal is emitted when a form is about to be submitted. The @request +argument passed contains information about the text fields of the form. This +is typically used to store login information that can be used later to +pre-fill the form. +The form will not be submitted until webkit_form_submission_request_submit() is called. + +It is possible to handle the form submission request asynchronously, by +simply calling g_object_ref() on the @request argument and calling +webkit_form_submission_request_submit() when done to continue with the form submission. +If the last reference is removed on a #WebKitFormSubmissionRequest and the +form has not been submitted, webkit_form_submission_request_submit() will be called. + + + + + + a #WebKitFormSubmissionRequest + + + + + + This signal is emitted when the web process crashes. + Use WebKitWebView::web-process-terminated instead. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to propagate the event further. + + + + + This signal is emitted when the web process terminates abnormally due +to @reason. + + + + + + the a #WebKitWebProcessTerminationReason + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #WebKitWebViewSessionState from serialized data. + + + a new #WebKitWebViewSessionState, or %NULL if @data doesn't contain a + valid serialized #WebKitWebViewSessionState. + + + + + a #GBytes + + + + + + Atomically increments the reference count of @state by one. This +function is MT-safe and may be called from any thread. + + + The passed in #WebKitWebViewSessionState + + + + + a #WebKitWebViewSessionState + + + + + + Serializes a #WebKitWebViewSessionState. + + + a #GBytes containing the @state serialized. + + + + + a #WebKitWebViewSessionState + + + + + + Atomically decrements the reference count of @state by one. If the +reference count drops to 0, all memory allocated by the #WebKitWebViewSessionState is +released. This function is MT-safe and may be called from any thread. + + + + + + + a #WebKitWebViewSessionState + + + + + + + + + Gets the name of #WebKitWebsiteData. This is the website name, normally represented by +a domain or host name. All local documents are grouped in the same #WebKitWebsiteData using +the name "Local files". + + + the website name of @website_data. + + + + + a #WebKitWebsiteData + + + + + + Gets the size of the data of types @types in a #WebKitWebsiteData. +Note that currently the data size is only known for %WEBKIT_WEBSITE_DATA_DISK_CACHE data type +so for all other types 0 will be returned. + + + the size of @website_data for the given @types. + + + + + a #WebKitWebsiteData + + + + a bitmask of #WebKitWebsiteDataTypes + + + + + + Gets the types of data stored in the client for a #WebKitWebsiteData. These are the +types actually present, not the types queried with webkit_website_data_manager_fetch(). + + + a bitmask of #WebKitWebsiteDataTypes in @website_data + + + + + a #WebKitWebsiteData + + + + + + Atomically increments the reference count of @website_data by one. +This function is MT-safe and may be called from any thread. + + + The passed #WebKitWebsiteData + + + + + a #WebKitWebsiteData + + + + + + Atomically decrements the reference count of @website_data by one. +If the reference count drops to 0, all memory allocated by +#WebKitWebsiteData is released. This function is MT-safe and may be +called from any thread. + + + + + + + A #WebKitWebsiteData + + + + + + + + + Creates a new #WebKitWebsiteDataManager with the given options. It must +be passed as construction parameter of a #WebKitWebContext. + + + the newly created #WebKitWebsiteDataManager + + + + + name of the first option to set + + + + value of first option, followed by more options, %NULL-terminated + + + + + + Creates an ephemeral #WebKitWebsiteDataManager. See #WebKitWebsiteDataManager:is-ephemeral for more details. + + + a new ephemeral #WebKitWebsiteDataManager. + + + + + Asynchronously clear the website data of the given @types modified in the past @timespan. +If @timespan is 0, all website data will be removed. + +When the operation is finished, @callback will be called. You can then call +webkit_website_data_manager_clear_finish() to get the result of the operation. + +Due to implementation limitations, this function does not currently delete +any stored cookies if @timespan is nonzero. This behavior may change in the +future. + + + + + + + a #WebKitWebsiteDataManager + + + + #WebKitWebsiteDataTypes + + + + a #GTimeSpan + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_website_data_manager_clear() + + + %TRUE if website data was successfully cleared, or %FALSE otherwise. + + + + + a #WebKitWebsiteDataManager + + + + a #GAsyncResult + + + + + + Asynchronously get the list of #WebKitWebsiteData for the given @types. + +When the operation is finished, @callback will be called. You can then call +webkit_website_data_manager_fetch_finish() to get the result of the operation. + + + + + + + a #WebKitWebsiteDataManager + + + + #WebKitWebsiteDataTypes + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_website_data_manager_fetch(). + + + a #GList of #WebKitWebsiteData. You must free the #GList with + g_list_free() and unref the #WebKitWebsiteData<!-- -->s with webkit_website_data_unref() when you're done with them. + + + + + + + a #WebKitWebsiteDataManager + + + + a #GAsyncResult + + + + + + Get the #WebKitWebsiteDataManager:base-cache-directory property. + + + the base directory for Website cache, or %NULL if + #WebKitWebsiteDataManager:base-cache-directory was not provided or @manager is ephemeral. + + + + + a #WebKitWebsiteDataManager + + + + + + Get the #WebKitWebsiteDataManager:base-data-directory property. + + + the base directory for Website data, or %NULL if + #WebKitWebsiteDataManager:base-data-directory was not provided or @manager is ephemeral. + + + + + a #WebKitWebsiteDataManager + + + + + + Get the #WebKitCookieManager of @manager. + + + a #WebKitCookieManager + + + + + a #WebKitWebsiteDataManager + + + + + + Get the #WebKitWebsiteDataManager:disk-cache-directory property. + + + the directory where HTTP disk cache is stored or %NULL if @manager is ephemeral. + + + + + a #WebKitWebsiteDataManager + + + + + + Get the #WebKitWebsiteDataManager:hsts-cache-directory property. + + + the directory where the HSTS cache is stored or %NULL if @manager is ephemeral. + + + + + a #WebKitWebsiteDataManager + + + + + + Get the #WebKitWebsiteDataManager:indexeddb-directory property. + + + the directory where IndexedDB databases are stored or %NULL if @manager is ephemeral. + + + + + a #WebKitWebsiteDataManager + + + + + + Get the #WebKitWebsiteDataManager:local-storage-directory property. + + + the directory where local storage data is stored or %NULL if @manager is ephemeral. + + + + + a #WebKitWebsiteDataManager + + + + + + Get the #WebKitWebsiteDataManager:offline-application-cache-directory property. + + + the directory where offline web application cache is stored or %NULL if @manager is ephemeral. + + + + + a #WebKitWebsiteDataManager + + + + + + Get the #WebKitWebsiteDataManager:websql-directory property. + WebSQL is no longer supported. Use IndexedDB instead. + + + the directory where WebSQL databases are stored or %NULL if @manager is ephemeral. + + + + + a #WebKitWebsiteDataManager + + + + + + Get whether a #WebKitWebsiteDataManager is ephemeral. See #WebKitWebsiteDataManager:is-ephemeral for more details. + + + %TRUE if @manager is ephemeral or %FALSE otherwise. + + + + + a #WebKitWebsiteDataManager + + + + + + Asynchronously removes the website data of the for the given @types for websites in the given @website_data list. +Use webkit_website_data_manager_clear() if you want to remove the website data for all sites. + +When the operation is finished, @callback will be called. You can then call +webkit_website_data_manager_remove_finish() to get the result of the operation. + + + + + + + a #WebKitWebsiteDataManager + + + + #WebKitWebsiteDataTypes + + + + a #GList of #WebKitWebsiteData + + + + + + a #GCancellable or %NULL to ignore + + + + a #GAsyncReadyCallback to call when the request is satisfied + + + + the data to pass to callback function + + + + + + Finish an asynchronous operation started with webkit_website_data_manager_remove(). + + + %TRUE if website data resources were successfully removed, or %FALSE otherwise. + + + + + a #WebKitWebsiteDataManager + + + + a #GAsyncResult + + + + + + The base directory for Website cache. This is used as a base directory +for any Website cache when no specific cache directory has been provided. + + + + The base directory for Website data. This is used as a base directory +for any Website data when no specific data directory has been provided. + + + + The directory where HTTP disk cache will be stored. + + + + The directory where the HTTP Strict-Transport-Security (HSTS) cache will be stored. + + + + The directory where IndexedDB databases will be stored. + + + + Whether the #WebKitWebsiteDataManager is ephemeral. An ephemeral #WebKitWebsiteDataManager +handles all websites data as non-persistent, and nothing will be written to the client +storage. Note that if you create an ephemeral #WebKitWebsiteDataManager all other construction +parameters to configure data directories will be ignored. + + + + The directory where local storage data will be stored. + + + + The directory where offline web application cache will be stored. + + + + The directory where WebSQL databases will be stored. + WebSQL is no longer supported. Use IndexedDB instead. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values with flags representing types of Website data. + + Memory cache. + + + HTTP disk cache. + + + Offline web application cache. + + + Session storage data. + + + Local storage data. + + + WebSQL databases. Deprecated 2.24 + + + IndexedDB databases. + + + Plugins data. + + + Cookies. + + + Hash salt used to generate the device ids used by webpages. Since 2.24 + + + HSTS cache. Since 2.26 + + + All types. + + + + + + Get whether the window should be shown in fullscreen state or not. + + + %TRUE if the window should be fullscreen or %FALSE otherwise. + + + + + a #WebKitWindowProperties + + + + + + Get the geometry the window should have on the screen when shown. + + + + + + + a #WebKitWindowProperties + + + + return location for the window geometry + + + + + + Get whether the window should have the locationbar visible or not. + + + %TRUE if locationbar should be visible or %FALSE otherwise. + + + + + a #WebKitWindowProperties + + + + + + Get whether the window should have the menubar visible or not. + + + %TRUE if menubar should be visible or %FALSE otherwise. + + + + + a #WebKitWindowProperties + + + + + + Get whether the window should be resizable by the user or not. + + + %TRUE if the window should be resizable or %FALSE otherwise. + + + + + a #WebKitWindowProperties + + + + + + Get whether the window should have the scrollbars visible or not. + + + %TRUE if scrollbars should be visible or %FALSE otherwise. + + + + + a #WebKitWindowProperties + + + + + + Get whether the window should have the statusbar visible or not. + + + %TRUE if statusbar should be visible or %FALSE otherwise. + + + + + a #WebKitWindowProperties + + + + + + Get whether the window should have the toolbar visible or not. + + + %TRUE if toolbar should be visible or %FALSE otherwise. + + + + + a #WebKitWindowProperties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the major version number of the WebKit library. +(e.g. in WebKit version 1.8.3 this is 1.) + +This function is in the library, so it represents the WebKit library +your code is running against. Contrast with the #WEBKIT_MAJOR_VERSION +macro, which represents the major version of the WebKit headers you +have included when compiling your code. + + + the major version number of the WebKit library + + + + + Returns the micro version number of the WebKit library. +(e.g. in WebKit version 1.8.3 this is 3.) + +This function is in the library, so it represents the WebKit library +your code is running against. Contrast with the #WEBKIT_MICRO_VERSION +macro, which represents the micro version of the WebKit headers you +have included when compiling your code. + + + the micro version number of the WebKit library + + + + + Returns the minor version number of the WebKit library. +(e.g. in WebKit version 1.8.3 this is 8.) + +This function is in the library, so it represents the WebKit library +your code is running against. Contrast with the #WEBKIT_MINOR_VERSION +macro, which represents the minor version of the WebKit headers you +have included when compiling your code. + + + the minor version number of the WebKit library + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use this function to format a URI for display. The URIs used internally by +WebKit may contain percent-encoded characters or Punycode, which are not +generally suitable to display to users. This function provides protection +against IDN homograph attacks, so in some cases the host part of the returned +URI may be in Punycode if the safety check fails. + + + @uri suitable for display, or %NULL in + case of error. + + + + + the URI to be converted + + + + + + + + + + + + + %TRUE if access to an audio device was requested. + + + + + a #WebKitUserMediaPermissionRequest + + + + + + + + %TRUE if access to a video device was requested. + + + + + a #WebKitUserMediaPermissionRequest + + + + + + diff --git a/gir-files/WebKit2WebExtension-4.0.gir b/gir-files/WebKit2WebExtension-4.0.gir new file mode 100644 index 0000000..b8494fb --- /dev/null +++ b/gir-files/WebKit2WebExtension-4.0.gir @@ -0,0 +1,29259 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Make a copy of @console_message. + + + A copy of passed in #WebKitConsoleMessage + + + + + a #WebKitConsoleMessage + + + + + + Free the #WebKitConsoleMessage + + + + + + + a #WebKitConsoleMessage + + + + + + Gets the log level of a #WebKitConsoleMessage + + + a #WebKitConsoleMessageLevel indicating the log level of @console_message + + + + + a #WebKitConsoleMessage + + + + + + Gets the line number of a #WebKitConsoleMessage + + + the line number of @console_message + + + + + a #WebKitConsoleMessage + + + + + + Gets the source of a #WebKitConsoleMessage + + + a #WebKitConsoleMessageSource indicating the source of @console_message + + + + + a #WebKitConsoleMessage + + + + + + Gets the source identifier of a #WebKitConsoleMessage + + + the source identifier of @console_message + + + + + a #WebKitConsoleMessage + + + + + + Gets the text message of a #WebKitConsoleMessage + + + the text message of @console_message + + + + + a #WebKitConsoleMessage + + + + + + + Enum values used to denote the various levels of console messages. + + Information message. + + + Log message. + + + Warning message. + + + Error message. + + + Debug message. + + + + Enum values used to denote the various sources of console messages. + + Message produced by JavaScript. + + + Network messages. + + + Messages produced by console API. + + + Security messages. + + + Other messages. + + + + + + Creates a new #WebKitContextMenu object to be used as a submenu of an existing +#WebKitContextMenu. The context menu of a #WebKitWebView is created by the view +and passed as an argument of #WebKitWebView::context-menu signal. +To add items to the menu use webkit_context_menu_prepend(), +webkit_context_menu_append() or webkit_context_menu_insert(). +See also webkit_context_menu_new_with_items() to create a #WebKitContextMenu with +a list of initial items. + + + The newly created #WebKitContextMenu object + + + + + Creates a new #WebKitContextMenu object to be used as a submenu of an existing +#WebKitContextMenu with the given initial items. +See also webkit_context_menu_new() + + + The newly created #WebKitContextMenu object + + + + + a #GList of #WebKitContextMenuItem + + + + + + + + Adds @item at the end of the @menu. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to add + + + + + + Gets the first item in the @menu. + + + the first #WebKitContextMenuItem of @menu, + or %NULL if the #WebKitContextMenu is empty. + + + + + a #WebKitContextMenu + + + + + + Gets the item at the given position in the @menu. + + + the #WebKitContextMenuItem at position @position in @menu, + or %NULL if the position is off the end of the @menu. + + + + + a #WebKitContextMenu + + + + the position of the item, counting from 0 + + + + + + Returns the item list of @menu. + + + a #GList of + #WebKitContextMenuItem<!-- -->s + + + + + + + a #WebKitContextMenu + + + + + + Gets the length of the @menu. + + + the number of #WebKitContextMenuItem<!-- -->s in @menu + + + + + a #WebKitContextMenu + + + + + + Gets the user data of @menu. +This function can be used from the UI Process to get user data previously set +from the Web Process with webkit_context_menu_set_user_data(). + + + the user data of @menu, or %NULL if @menu doesn't have user data + + + + + a #WebKitContextMenu + + + + + + Inserts @item into the @menu at the given position. +If @position is negative, or is larger than the number of items +in the #WebKitContextMenu, the item is added on to the end of +the @menu. The first position is 0. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to add + + + + the position to insert the item + + + + + + Gets the last item in the @menu. + + + the last #WebKitContextMenuItem of @menu, + or %NULL if the #WebKitContextMenu is empty. + + + + + a #WebKitContextMenu + + + + + + Moves @item to the given position in the @menu. +If @position is negative, or is larger than the number of items +in the #WebKitContextMenu, the item is added on to the end of +the @menu. +The first position is 0. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to add + + + + the new position to move the item + + + + + + Adds @item at the beginning of the @menu. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to add + + + + + + Removes @item from the @menu. +See also webkit_context_menu_remove_all() to remove all items. + + + + + + + a #WebKitContextMenu + + + + the #WebKitContextMenuItem to remove + + + + + + Removes all items of the @menu. + + + + + + + a #WebKitContextMenu + + + + + + Sets user data to @menu. +This function can be used from a Web Process extension to set user data +that can be retrieved from the UI Process using webkit_context_menu_get_user_data(). +If the @user_data #GVariant is floating, it is consumed. + + + + + + + a #WebKitContextMenu + + + + a #GVariant + + + + + + + Enum values used to denote the stock actions for +#WebKitContextMenuItem<!-- -->s + + + No action, used by separator menu items. + + + Open current link. + + + Open current link in a new window. + + + Download link destination. + + + Copy link location to the clipboard. + + + Open current image in a new window. + + + Download current image. + + + Copy current image to the clipboard. + + + Copy current image location to the clipboard. + + + Open current frame in a new window. + + + Load the previous history item. + + + Load the next history item. + + + Stop any ongoing loading operation. + + + Reload the contents of current view. + + + Copy current selection the clipboard. + + + Cut current selection to the clipboard. + + + Paste clipboard contents. + + + Delete current selection. + + + Select all text. + + + Input methods menu. + + + Unicode menu. + + + A proposed replacement for a misspelled word. + + + An indicator that spellchecking found no proposed replacements. + + + Causes the spellchecker to ignore the word for this session. + + + Causes the spellchecker to add the word to the dictionary. + + + Ignore grammar. + + + Font options menu. + + + Bold. + + + Italic. + + + Underline. + + + Outline. + + + Open current element in the inspector. + + + Open current video element in a new window. + + + Open current audio element in a new window. + + + Copy video link location in to the clipboard. + + + Copy audio link location in to the clipboard. + + + Enable or disable media controls. + + + Enable or disable media loop. + + + Show current video element in fullscreen mode. + + + Play current media element. + + + Pause current media element. + + + Mute current media element. + + + Download video to disk. Since 2.2 + + + Download audio to disk. Since 2.2 + + + Insert an emoji. Since 2.26 + + + Custom action defined by applications. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #WebKitContextMenuItem for the given @action. + Use webkit_context_menu_item_new_from_gaction() instead. + + + the newly created #WebKitContextMenuItem object. + + + + + a #GtkAction + + + + + + Creates a new #WebKitContextMenuItem for the given @action and @label. On activation +@target will be passed as parameter to the callback. + + + the newly created #WebKitContextMenuItem object. + + + + + a #GAction + + + + the menu item label text + + + + a #GVariant to use as the action target + + + + + + Creates a new #WebKitContextMenuItem for the given stock action. +Stock actions are handled automatically by WebKit so that, for example, +when a menu item created with a %WEBKIT_CONTEXT_MENU_ACTION_STOP is +activated the action associated will be handled by WebKit and the current +load operation will be stopped. You can get the #GtkAction of a +#WebKitContextMenuItem created with a #WebKitContextMenuAction with +webkit_context_menu_item_get_action() and connect to #GtkAction::activate signal +to be notified when the item is activated. But you can't prevent the associated +action from being performed. + + + the newly created #WebKitContextMenuItem object. + + + + + a #WebKitContextMenuAction stock action + + + + + + Creates a new #WebKitContextMenuItem for the given stock action using the given @label. +Stock actions have a predefined label, this method can be used to create a +#WebKitContextMenuItem for a #WebKitContextMenuAction but using a custom label. + + + the newly created #WebKitContextMenuItem object. + + + + + a #WebKitContextMenuAction stock action + + + + a custom label text to use instead of the predefined one + + + + + + Creates a new #WebKitContextMenuItem representing a separator. + + + the newly created #WebKitContextMenuItem object. + + + + + Creates a new #WebKitContextMenuItem using the given @label with a submenu. + + + the newly created #WebKitContextMenuItem object. + + + + + the menu item label text + + + + a #WebKitContextMenu to set + + + + + + Gets the action associated to @item as a #GtkAction. + Use webkit_context_menu_item_get_gaction() instead. + + + the #GtkAction associated to the #WebKitContextMenuItem, + or %NULL if @item is a separator. + + + + + a #WebKitContextMenuItem + + + + + + Gets the action associated to @item as a #GAction. + + + the #GAction associated to the #WebKitContextMenuItem, + or %NULL if @item is a separator. + + + + + a #WebKitContextMenuItem + + + + + + Gets the #WebKitContextMenuAction of @item. If the #WebKitContextMenuItem was not +created for a stock action %WEBKIT_CONTEXT_MENU_ACTION_CUSTOM will be +returned. If the #WebKitContextMenuItem is a separator %WEBKIT_CONTEXT_MENU_ACTION_NO_ACTION +will be returned. + + + the #WebKitContextMenuAction of @item + + + + + a #WebKitContextMenuItem + + + + + + Gets the submenu of @item. + + + the #WebKitContextMenu representing the submenu of + @item or %NULL if @item doesn't have a submenu. + + + + + a #WebKitContextMenuItem + + + + + + Checks whether @item is a separator. + + + %TRUE is @item is a separator or %FALSE otherwise + + + + + a #WebKitContextMenuItem + + + + + + Sets or replaces the @item submenu. If @submenu is %NULL the current +submenu of @item is removed. + + + + + + + a #WebKitContextMenuItem + + + + a #WebKitContextMenu + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMAttr + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #guint64 + + + + + A #WebKitDOMBlob + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCSSRule + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSRule + + + + + A #WebKitDOMCSSRule + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSStyleSheet + + + + + A #WebKitDOMCSSRule + + + + + + Use JavaScriptCore API instead + + + A #gushort + + + + + A #WebKitDOMCSSRule + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCSSRule + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMCSSRuleList + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSRule + + + + + A #WebKitDOMCSSRuleList + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCSSStyleDeclaration + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMCSSStyleDeclaration + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSRule + + + + + A #WebKitDOMCSSStyleDeclaration + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCSSStyleDeclaration + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCSSStyleDeclaration + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCSSStyleDeclaration + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMCSSStyleDeclaration + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCSSStyleDeclaration + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCSSStyleDeclaration + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCSSStyleDeclaration + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCSSStyleDeclaration + + + + A #gchar + + + + A #gchar + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMCSSStyleSheet + + + + A #gchar + + + + A #gchar + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCSSStyleSheet + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSRuleList + + + + + A #WebKitDOMCSSStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSRule + + + + + A #WebKitDOMCSSStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSRuleList + + + + + A #WebKitDOMCSSStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMCSSStyleSheet + + + + A #gchar + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCSSStyleSheet + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCSSValue + + + + + + Use JavaScriptCore API instead + + + A #gushort + + + + + A #WebKitDOMCSSValue + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCSSValue + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCharacterData + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCharacterData + + + + A #gulong + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCharacterData + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMCharacterData + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCharacterData + + + + A #gulong + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCharacterData + + + + A #gulong + + + + A #gulong + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMCharacterData + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMCharacterData + + + + A #gulong + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + + + Returns the bottom coordinate of @self, relative to the viewport. + Use JavaScriptCore API instead + + + A #gfloat + + + + + A #WebKitDOMClientRect + + + + + + Returns the height of @self. + Use JavaScriptCore API instead + + + A #gfloat + + + + + A #WebKitDOMClientRect + + + + + + Returns the left coordinate of @self, relative to the viewport. + Use JavaScriptCore API instead + + + A #gfloat + + + + + A #WebKitDOMClientRect + + + + + + Returns the right coordinate of @self, relative to the viewport. + Use JavaScriptCore API instead + + + A #gfloat + + + + + A #WebKitDOMClientRect + + + + + + Returns the top coordinate of @self, relative to the viewport. + Use JavaScriptCore API instead + + + A #gfloat + + + + + A #WebKitDOMClientRect + + + + + + Returns the width of @self. + Use JavaScriptCore API instead + + + A #gfloat + + + + + A #WebKitDOMClientRect + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the number of #WebKitDOMClientRect objects that @self contains. + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMClientRectList + + + + + + Returns the #WebKitDOMClientRect object that @self contains at @index. + Use JavaScriptCore API instead + + + A #WebKitDOMClientRect + + + + + A #WebKitDOMClientRectList + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSStyleSheet + + + + + A #WebKitDOMDOMImplementation + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocument + + + + + A #WebKitDOMDOMImplementation + + + + A #gchar + + + + A #gchar + + + + A #WebKitDOMDocumentType + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocumentType + + + + + A #WebKitDOMDOMImplementation + + + + A #gchar + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLDocument + + + + + A #WebKitDOMDOMImplementation + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMImplementation + + + + A #gchar + + + + A #gchar + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + A #WebKitDOMNode + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMSelection + + + + A #WebKitDOMNode + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + A #WebKitDOMNode + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMRange + + + + + A #WebKitDOMDOMSelection + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + A #gchar + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + A #WebKitDOMNode + + + + A #gulong + + + + A #WebKitDOMNode + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMSelection + + + + A #WebKitDOMNode + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMTokenList + + + + #GError + + + + list of #gchar ended by %NULL. + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMTokenList + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDOMTokenList + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDOMTokenList + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDOMTokenList + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMTokenList + + + + #GError + + + + list of #gchar ended by %NULL. + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMTokenList + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMTokenList + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMTokenList + + + + A #gchar + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMWindow + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMWindow + + + + A #gchar + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSStyleDeclaration + + + + + A #WebKitDOMDOMWindow + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocument + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMSelection + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gfloat + + + + A #gfloat + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gfloat + + + + A #gfloat + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDOMWindow + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gfloat + + + + A #gfloat + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gfloat + + + + A #gfloat + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gdouble + + + + A #gdouble + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gdouble + + + + A #gdouble + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDOMWindow + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMDocument + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMRange + + + + + A #WebKitDOMDocument + + + + A #glong + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMAttr + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMAttr + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCDATASection + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMComment + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSStyleDeclaration + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocumentFragment + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + A #gchar + + + + + + This function has been removed from the DOM spec and it just returns %NULL. + + + A #WebKitDOMEntityReference + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMEvent + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMXPathExpression + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + A #WebKitDOMXPathNSResolver + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNodeIterator + + + + + A #WebKitDOMDocument + + + + A #WebKitDOMNode + + + + A #gulong + + + + A #WebKitDOMNodeFilter + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMXPathNSResolver + + + + + A #WebKitDOMDocument + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMProcessingInstruction + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMRange + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMText + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMTreeWalker + + + + + A #WebKitDOMDocument + + + + A #WebKitDOMNode + + + + A #gulong + + + + A #WebKitDOMNodeFilter + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + A #glong + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMXPathResult + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + A #WebKitDOMNode + + + + A #WebKitDOMXPathNSResolver + + + + A #gushort + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + A #gboolean + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLElement + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLScriptElement + + + + + A #WebKitDOMDocument + + + + + + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocumentType + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use webkit_dom_document_get_elements_by_class_name_as_html_collection() instead. + + + a #WebKitDOMNodeList + + + + + A #WebKitDOMDocument + + + + a #gchar with the tag name + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNodeList + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use webkit_dom_document_get_elements_by_tag_name_as_html_collection() instead. + + + a #WebKitDOMNodeList + + + + + A #WebKitDOMDocument + + + + a #gchar with the tag name + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use webkit_dom_document_get_elements_by_tag_name_ns_as_html_collection() instead. + + + a #WebKitDOMNodeList + + + + + A #WebKitDOMDocument + + + + a #gchar with the namespace URI + + + + a #gchar with the tag name + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLHeadElement + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMImplementation + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSStyleDeclaration + + + + + A #WebKitDOMDocument + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + + + This function has been removed and does nothing. + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + + + This function has been removed and does nothing. + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMStyleSheetList + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMDocument + + + + A #WebKitDOMNode + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNodeList + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + This function has been removed and does nothing. + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMDocument + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMDocumentFragment + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMDocumentFragment + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocumentFragment + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocumentFragment + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocumentFragment + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMDocumentFragment + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNodeList + + + + + A #WebKitDOMDocumentFragment + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNamedNodeMap + + + + + A #WebKitDOMDocumentType + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocumentType + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocumentType + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNamedNodeMap + + + + + A #WebKitDOMDocumentType + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocumentType + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMDocumentType + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMAttr + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMAttr + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNamedNodeMap + + + + + A #WebKitDOMElement + + + + + + Returns a #WebKitDOMClientRect representing the size and position of @self +relative to the viewport. + Use JavaScriptCore API instead + + + A #WebKitDOMClientRect + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMTokenList + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMElement + + + + + + Returns a collection of #WebKitDOMClientRect objects, each of which describe +the size and position of a CSS border box relative to the viewport. + Use JavaScriptCore API instead + + + A #WebKitDOMClientRectList + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMElement + + + + + + Use webkit_dom_element_get_elements_by_class_name_as_html_collection() instead. + + + a #WebKitDOMNodeList + + + + + A #WebKitDOMElement + + + + a #gchar with the tag name + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use webkit_dom_element_get_elements_by_tag_name_as_html_collection() instead. + + + a #WebKitDOMNodeList + + + + + A #WebKitDOMElement + + + + a #gchar with the tag name + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use webkit_dom_element_get_elements_by_tag_name_ns_as_html_collection() instead. + + + a #WebKitDOMNodeList + + + + + A #WebKitDOMElement + + + + a #gchar with the namespace URI + + + + a #gchar with the tag name + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMCSSStyleDeclaration + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMElement + + + + + + CSS Regions support has been removed. This function does nothing. + + + %NULL + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMElement + + + + + + + + + + + + + + + + + Get whether @element is an HTML text input element that has been edited by a user action. + + + whether @element has been edited by a user action. + + + + + a #WebKitDOMElement + + + + + + Set whether the element is an HTML input element that has been filled automatically. +If @element is not an HTML input element this function does nothing. + + + + + + + a #WebKitDOMElement + + + + value to set + + + + + + Set the value of an HTML input element as if it had been edited by +the user, triggering a change event. If @element is not an HTML input +element this function does nothing. + + + + + + + a #WebKitDOMElement + + + + the text to set + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNodeList + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMAttr + + + + + A #WebKitDOMElement + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMAttr + + + + + A #WebKitDOMElement + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMAttr + + + + + A #WebKitDOMElement + + + + A #WebKitDOMAttr + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMElement + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMEventTarget + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #gushort + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMEventTarget + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMEventTarget + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + A #guint32 + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMEvent + + + + A #gchar + + + + A #gboolean + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMEvent + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMEvent + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMEvent + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #gchar + + + + A #GCallback + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #gchar + + + + A #GCallback + + + + A #gboolean + + + + A #gpointer + + + + + + Version of webkit_dom_event_target_add_event_listener() using a closure +instead of a callbacks for easier binding in other languages. + Use JavaScriptCore API instead + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #gchar + + + + A #GClosure + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #WebKitDOMEvent + + + + + + Use JavaScriptCore API instead + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #gchar + + + + A #GCallback + + + + A #gboolean + + + + + + Version of webkit_dom_event_target_remove_event_listener() using a closure +instead of a callbacks for easier binding in other languages. + Use JavaScriptCore API instead + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #gchar + + + + A #GClosure + + + + A #gboolean + + + + + + + + + + + + + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #WebKitDOMEvent + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #gboolean + + + + + A #WebKitDOMEventTarget + + + + A #gchar + + + + A #GCallback + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMFile + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMFileList + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMFile + + + + + A #WebKitDOMFileList + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAnchorElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAnchorElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAppletElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAppletElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLAreaElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLAreaElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBRElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBRElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBaseElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBaseElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBaseElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBaseElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + This function has been removed from the DOM spec and it just returns %NULL. + + + A #gchar + + + + + A #WebKitDOMHTMLBaseFontElement + + + + + + This function has been removed from the DOM spec and it just returns %NULL. + + + A #gchar + + + + + A #WebKitDOMHTMLBaseFontElement + + + + + + This function has been removed from the DOM spec and it just returns 0. + + + A #glong + + + + + A #WebKitDOMHTMLBaseFontElement + + + + + + This function has been removed from the DOM spec and it does nothing. + + + + + + + A #WebKitDOMHTMLBaseFontElement + + + + A #gchar + + + + + + This function has been removed from the DOM spec and it does nothing. + + + + + + + A #WebKitDOMHTMLBaseFontElement + + + + A #gchar + + + + + + This function has been removed from the DOM spec and it does nothing. + + + + + + + A #WebKitDOMHTMLBaseFontElement + + + + A #glong + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBodyElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBodyElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBodyElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBodyElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBodyElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLBodyElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBodyElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBodyElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBodyElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBodyElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBodyElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLBodyElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLButtonElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLButtonElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLButtonElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLButtonElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLButtonElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLButtonElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLButtonElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLButtonElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLButtonElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLButtonElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLButtonElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLButtonElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLCanvasElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLCanvasElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLCanvasElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLCanvasElement + + + + A #glong + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMHTMLCollection + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMHTMLCollection + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMHTMLCollection + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLDListElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDListElement + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLDirectoryElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDirectoryElement + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLDivElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDivElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLDocument + + + + + + Use webkit_dom_document_get_compat_mode() instead. + + + A #gchar + + + + + A #WebKitDOMHTMLDocument + + + + + + Use webkit_dom_document_get_design_mode() instead. + + + A #gchar + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLDocument + + + + + + Use webkit_dom_document_get_embeds() instead. + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLDocument + + + + + + Use webkit_dom_document_get_plugins() instead. + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLDocument + + + + + + Use webkit_dom_document_get_scripts() instead. + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + A #gchar + + + + + + Use webkit_dom_document_set_design_mode() instead. + + + + + + + A #WebKitDOMHTMLDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLDocument + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLElement + + + + + + Use webkit_dom_element_get_children() instead. + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLElement + + + + + + Use webkit_dom_element_get_inner_html() instead. + + + a #gchar + + + + + a #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLElement + + + + + + Use webkit_dom_element_get_outer_html() instead. + + + a #gchar + + + + + a #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gboolean + + + + + + Use webkit_dom_element_set_inner_html() instead. + + + + + + + a #WebKitDOMHTMLElement + + + + a #gchar with contents to set + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gchar + + + + + + Use webkit_dom_element_set_outer_html() instead. + + + + + + + a #WebKitDOMHTMLElement + + + + a #gchar with contents to set + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLEmbedElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLEmbedElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLEmbedElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLEmbedElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLEmbedElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLEmbedElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLEmbedElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLEmbedElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLEmbedElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLEmbedElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLEmbedElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLEmbedElement + + + + A #glong + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLFieldSetElement + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFontElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFontElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFontElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFontElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFontElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFontElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFormElement + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocument + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLFrameElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameSetElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLFrameSetElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameSetElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLFrameSetElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLHRElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLHRElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLHRElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLHRElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLHRElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLHRElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLHRElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLHRElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLHeadElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLHeadElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLHeadingElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLHeadingElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLHtmlElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLHtmlElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocument + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLIFrameElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLIFrameElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLImageElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLImageElement + + + + A #glong + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use webkit_dom_element_html_input_element_get_auto_filled() instead. + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use webkit_dom_html_input_element_get_capture_type() instead. + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMFileList + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use webkit_dom_element_html_input_element_is_user_edited() instead. + + + A #gboolean + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use webkit_dom_element_html_input_element_set_auto_filled() instead. + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gboolean + + + + + + Use webkit_dom_element_html_input_element_set_editing_value() instead. + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #WebKitDOMFileList + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLInputElement + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLIElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLLIElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLIElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLIElement + + + + A #glong + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLLabelElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLabelElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLabelElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLegendElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLLegendElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLegendElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMStyleSheet + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMTokenList + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLLinkElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + a #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLLinkElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLMapElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLMapElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLMapElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLMarqueeElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLMarqueeElement + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLMenuElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLMenuElement + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLMetaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLMetaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLMetaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLMetaElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLMetaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLMetaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLMetaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLMetaElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLModElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLModElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLModElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLModElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLOListElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLOListElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLOListElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOListElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOListElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOListElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocument + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLObjectElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLObjectElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLOptGroupElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLOptGroupElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOptGroupElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOptGroupElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLOptionElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLOptionElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLOptionElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLOptionElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLOptionElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLOptionElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLOptionElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLOptionElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOptionElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOptionElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOptionElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOptionElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOptionElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMHTMLOptionsCollection + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLOptionsCollection + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMHTMLOptionsCollection + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLOptionsCollection + + + + A #glong + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLParagraphElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLParagraphElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLParamElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLParamElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLParamElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLParamElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLParamElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLParamElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLParamElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLParamElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLPreElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLPreElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLPreElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLPreElement + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLQuoteElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLQuoteElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLScriptElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLScriptElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLScriptElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLScriptElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLScriptElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLScriptElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLScriptElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLScriptElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLScriptElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLScriptElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLScriptElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLScriptElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLScriptElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLScriptElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #WebKitDOMHTMLElement + + + + A #WebKitDOMHTMLElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLOptionsCollection + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLSelectElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMHTMLSelectElement + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMHTMLSelectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLSelectElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLStyleElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLStyleElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMStyleSheet + + + + + A #WebKitDOMHTMLStyleElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLStyleElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLStyleElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLStyleElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLStyleElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCaptionElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCaptionElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableCellElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableCellElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableColElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableColElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableColElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTableColElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableColElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableColElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableColElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableColElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableColElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableColElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableColElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableColElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLElement + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLElement + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLElement + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLTableCaptionElement + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLTableSectionElement + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLTableSectionElement + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLElement + + + + + A #WebKitDOMHTMLTableElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #WebKitDOMHTMLTableCaptionElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #WebKitDOMHTMLTableSectionElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #WebKitDOMHTMLTableSectionElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableRowElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableRowElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableRowElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLTableRowElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableRowElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableRowElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTableRowElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTableRowElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableRowElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLElement + + + + + A #WebKitDOMHTMLTableRowElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableRowElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableRowElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableRowElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableRowElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableRowElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableSectionElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableSectionElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableSectionElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableSectionElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLCollection + + + + + A #WebKitDOMHTMLTableSectionElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTableSectionElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLElement + + + + + A #WebKitDOMHTMLTableSectionElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableSectionElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableSectionElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableSectionElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTableSectionElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMHTMLFormElement + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #glong + + + + A #glong + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTextAreaElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLTitleElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLTitleElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMHTMLUListElement + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMHTMLUListElement + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLUListElement + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMHTMLUListElement + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMKeyboardEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMKeyboardEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMKeyboardEvent + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMKeyboardEvent + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMKeyboardEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMKeyboardEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMKeyboardEvent + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMKeyboardEvent + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMKeyboardEvent + + + + A #gchar + + + + A #gboolean + + + + A #gboolean + + + + A #WebKitDOMDOMWindow + + + + A #gchar + + + + A #gulong + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMMediaList + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMMediaList + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMMediaList + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMMediaList + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMMediaList + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMMediaList + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #gushort + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMEventTarget + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMMouseEvent + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMMouseEvent + + + + A #gchar + + + + A #gboolean + + + + A #gboolean + + + + A #WebKitDOMDOMWindow + + + + A #glong + + + + A #glong + + + + A #glong + + + + A #glong + + + + A #glong + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + A #gushort + + + + A #WebKitDOMEventTarget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMNamedNodeMap + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNamedNodeMap + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNamedNodeMap + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNamedNodeMap + + + + A #gulong + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNamedNodeMap + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNamedNodeMap + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNamedNodeMap + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNamedNodeMap + + + + A #WebKitDOMNode + + + + + + + + + + + + + + + + + + + + + + Get the #WebKitDOMNode for the DOM node referenced by @value. + + + a #WebKitDOMNode, or %NULL if @value doesn't reference a DOM node. + + + + + a #JSCValue + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + + + Use webkit_dom_node_clone_node_with_error() instead. + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + A #gushort + + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNodeList + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + + + Use webkit_dom_attr_get_local_name() or webkit_dom_element_get_local_name() instead. + + + A #gchar + + + + + A #WebKitDOMNode + + + + + + Use webkit_dom_attr_get_namespace_uri() or webkit_dom_element_get_namespace_uri() instead. + + + A #gchar + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gushort + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocument + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMElement + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + + + Use webkit_dom_attr_get_prefix() or webkit_dom_element_get_prefix() instead. + + + A #gchar + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMNode + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMNode + + + + A #gchar + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMNode + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMNode + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMNode + + + + A #gchar + + + + + + + + + + + + A #WebKitDOMNode + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMNode + + + + A #gchar + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + a #gshort + + + + + A #WebKitDOMNodeFilter + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + a #gshort + + + + + A #WebKitDOMNodeFilter + + + + A #WebKitDOMNode + + + + + + + + + + + + + + + a #gshort + + + + + A #WebKitDOMNodeFilter + + + + A #WebKitDOMNode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMNodeIterator + + + + + + This function has been removed from the DOM spec and it just returns %FALSE. + + + A #gboolean * + + + + + A #WebKitDOMNodeIterator + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNodeFilter + + + + + A #WebKitDOMNodeIterator + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMNodeIterator + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNodeIterator + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNodeIterator + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMNodeIterator + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNodeIterator + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNodeIterator + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMNodeList + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMNodeList + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMStyleSheet + + + + + A #WebKitDOMProcessingInstruction + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMProcessingInstruction + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocumentFragment + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMRange + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #gboolean + + + + + + Use JavaScriptCore API instead + + + A #gshort + + + + + A #WebKitDOMRange + + + + A #gushort + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #gshort + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gshort + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocumentFragment + + + + + A #WebKitDOMRange + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDocumentFragment + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMRange + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + A #glong + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMRange + + + + A #WebKitDOMNode + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMRange + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMMediaList + + + + + A #WebKitDOMStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMStyleSheet + + + + + A #WebKitDOMStyleSheet + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMStyleSheet + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMStyleSheet + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMStyleSheetList + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMStyleSheet + + + + + A #WebKitDOMStyleSheetList + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMText + + + + + + + + A #WebKitDOMText + + + + + A #WebKitDOMText + + + + A #gchar + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMText + + + + + A #WebKitDOMText + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + This function has been removed from the DOM spec and it just returns %FALSE. + + + A #gboolean + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNodeFilter + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMTreeWalker + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMTreeWalker + + + + A #WebKitDOMNode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMUIEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMUIEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMUIEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMUIEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMUIEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMUIEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMUIEvent + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMDOMWindow + + + + + A #WebKitDOMUIEvent + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMUIEvent + + + + A #gchar + + + + A #gboolean + + + + A #gboolean + + + + A #WebKitDOMDOMWindow + + + + A #glong + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMWheelEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMWheelEvent + + + + + + Use JavaScriptCore API instead + + + A #glong + + + + + A #WebKitDOMWheelEvent + + + + + + Use JavaScriptCore API instead + + + + + + + A #WebKitDOMWheelEvent + + + + A #glong + + + + A #glong + + + + A #WebKitDOMDOMWindow + + + + A #glong + + + + A #glong + + + + A #glong + + + + A #glong + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + A #gboolean + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMXPathResult + + + + + A #WebKitDOMXPathExpression + + + + A #WebKitDOMNode + + + + A #gushort + + + + A #WebKitDOMXPathResult + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + a #gchar + + + + + A #WebKitDOMXPathNSResolver + + + + The prefix to lookup + + + + + + Use JavaScriptCore API instead + + + a #gchar + + + + + A #WebKitDOMXPathNSResolver + + + + The prefix to lookup + + + + + + + + + + + + + + + a #gchar + + + + + A #WebKitDOMXPathNSResolver + + + + The prefix to lookup + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #gboolean + + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #gdouble + + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #gushort + + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #gulong + + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #gchar + + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMXPathResult + + + + + + Use JavaScriptCore API instead + + + A #WebKitDOMNode + + + + + A #WebKitDOMXPathResult + + + + A #gulong + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Accept the node. Use this macro as return value of webkit_dom_node_filter_accept_node() +implementation to accept the given #WebKitDOMNode + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + Reject the node. Use this macro as return value of webkit_dom_node_filter_accept_node() +implementation to reject the given #WebKitDOMNode. The children of the given node will +be rejected too. + Use JavaScriptCore API instead + + + + + Show all nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMAttr nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMCDataSection nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMComment nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMDocument nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMDocumentFragment nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMDocumentType nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMElement nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMEntity nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMEntityReference nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMNotation nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMProcessingInstruction nodes. + Use JavaScriptCore API instead + + + + + Show #WebKitDOMText nodes. + Use JavaScriptCore API instead + + + + + Skip the node. Use this macro as return value of webkit_dom_node_filter_accept_node() +implementation to skip the given #WebKitDOMNode. The children of the given node will +not be skipped. + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + Use JavaScriptCore API instead + + + + + + + + + + + + + + + + + + + + + + + + + + Used to indicate a particular stage in form submission. See +#WebKitWebPage::will-submit-form. + + indicates the form's +DOM submit event is about to be emitted. + + + indicates the form is about +to be submitted. + + + + + + Gets the process-unique identifier of this #WebKitFrame. No other +frame in the same web process will have the same ID; however, frames +in other web processes may. + + + the identifier of @frame + + + + + a #WebKitFrame + + + + + + Gets the JavaScript execution context of @frame for the given #WebKitScriptWorld. + Use webkit_frame_get_js_context_for_script_world() instead. + + + the JavaScript context of @frame for @world + + + + + a #WebKitFrame + + + + a #WebKitScriptWorld + + + + + + Gets the global JavaScript execution context. Use this function to bridge +between the WebKit and JavaScriptCore APIs. + Use webkit_frame_get_js_context() instead. + + + the global JavaScript context of @frame + + + + + a #WebKitFrame + + + + + + Get the JavaScript execution context of @frame. Use this function to bridge +between the WebKit and JavaScriptCore APIs. + + + the #JSCContext for the JavaScript execution context of @frame. + + + + + a #WebKitFrame + + + + + + Get the JavaScript execution context of @frame for the given #WebKitScriptWorld. + + + the #JSCContext for the JavaScript execution context of @frame for @world. + + + + + a #WebKitFrame + + + + a #WebKitScriptWorld + + + + + + Get a #JSCValue referencing the given DOM object. The value is created in the JavaScript execution +context of @frame. + + + the #JSCValue referencing @dom_object. + + + + + a #WebKitFrame + + + + a #WebKitDOMObject + + + + + + Get a #JSCValue referencing the given DOM object. The value is created in the JavaScript execution +context of @frame for the given #WebKitScriptWorld. + + + the #JSCValue referencing @dom_object + + + + + a #WebKitFrame + + + + a #WebKitDOMObject + + + + a #WebKitScriptWorld + + + + + + Gets the current active URI of @frame. + + + the current active URI of @frame or %NULL if nothing has been + loaded yet. + + + + + a #WebKitFrame + + + + + + Gets whether @frame is the main frame of a #WebKitWebPage + + + %TRUE if @frame is a main frame or %FALSE otherwise + + + + + a #WebKitFrame + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_EDITABLE flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's an editable element at the coordinates of the @hit_test_result, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_IMAGE flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's an image element in the coordinates of the Hit Test, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_LINK flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's a link element in the coordinates of the Hit Test, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_MEDIA flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's a media element in the coordinates of the Hit Test, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_SCROLLBAR flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's a scrollbar element at the coordinates of the @hit_test_result, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets whether %WEBKIT_HIT_TEST_RESULT_CONTEXT_SELECTION flag is present in +#WebKitHitTestResult:context. + + + %TRUE if there's a selected element at the coordinates of the @hit_test_result, + or %FALSE otherwise + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:context property. + + + a bitmask of #WebKitHitTestResultContext flags + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:image-uri property. + + + the URI of the image element in the coordinates of the Hit Test, + or %NULL if there isn't an image element in @hit_test_result context + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:link-label property. + + + the label of the link element in the coordinates of the Hit Test, + or %NULL if there isn't a link element in @hit_test_result context or the + link element doesn't have a label + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:link-title property. + + + the title of the link element in the coordinates of the Hit Test, + or %NULL if there isn't a link element in @hit_test_result context or the + link element doesn't have a title + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:link-uri property. + + + the URI of the link element in the coordinates of the Hit Test, + or %NULL if there isn't a link element in @hit_test_result context + + + + + a #WebKitHitTestResult + + + + + + Gets the value of the #WebKitHitTestResult:media-uri property. + + + the URI of the media element in the coordinates of the Hit Test, + or %NULL if there isn't a media element in @hit_test_result context + + + + + a #WebKitHitTestResult + + + + + + Bitmask of #WebKitHitTestResultContext flags representing +the context of the #WebKitHitTestResult. + + + + The URI of the image if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_IMAGE +is present in #WebKitHitTestResult:context + + + + The label of the link if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_LINK +is present in #WebKitHitTestResult:context + + + + The title of the link if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_LINK +is present in #WebKitHitTestResult:context + + + + The URI of the link if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_LINK +is present in #WebKitHitTestResult:context + + + + The URI of the media if flag %WEBKIT_HIT_TEST_RESULT_CONTEXT_MEDIA +is present in #WebKitHitTestResult:context + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Enum values with flags representing the context of a #WebKitHitTestResult. + + + anywhere in the document. + + + a hyperlink element. + + + an image element. + + + a video or audio element. + + + an editable element + + + a scrollbar element. + + + a selected element. Since 2.8 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new isolated #WebKitScriptWorld. Scripts executed in +isolated worlds have access to the DOM but not to other variable +or functions created by the page. +The #WebKitScriptWorld is created with a generated unique name. Use +webkit_script_world_new_with_name() if you want to create it with a +custom name. +You can get the JavaScript execution context of a #WebKitScriptWorld +for a given #WebKitFrame with webkit_frame_get_javascript_context_for_script_world(). + + + a new isolated #WebKitScriptWorld + + + + + Creates a new isolated #WebKitScriptWorld with a name. Scripts executed in +isolated worlds have access to the DOM but not to other variable +or functions created by the page. +You can get the JavaScript execution context of a #WebKitScriptWorld +for a given #WebKitFrame with webkit_frame_get_javascript_context_for_script_world(). + + + a new isolated #WebKitScriptWorld + + + + + a name for the script world + + + + + + Get the default #WebKitScriptWorld. This is the normal script world +where all scripts are executed by default. +You can get the JavaScript execution context of a #WebKitScriptWorld +for a given #WebKitFrame with webkit_frame_get_javascript_context_for_script_world(). + + + the default #WebKitScriptWorld + + + + + Get the name of a #WebKitScriptWorld. + + + the name of @world + + + + + a #WebKitScriptWorld + + + + + + + + + + + + Emitted when the JavaScript window object in a #WebKitScriptWorld has been +cleared. This is the preferred place to set custom properties on the window +object using the JavaScriptCore API. You can get the window object of @frame +from the JavaScript execution context of @world that is returned by +webkit_frame_get_js_context_for_script_world(). + + + + + + a #WebKitWebPage + + + + the #WebKitFrame to which @world belongs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #WebKitURIRequest for the given URI. + + + a new #WebKitURIRequest + + + + + an URI + + + + + + Get the HTTP headers of a #WebKitURIRequest as a #SoupMessageHeaders. + + + a #SoupMessageHeaders with the HTTP headers of @request + or %NULL if @request is not an HTTP request. + + + + + a #WebKitURIRequest + + + + + + Get the HTTP method of the #WebKitURIRequest. + + + the HTTP method of the #WebKitURIRequest or %NULL if @request is not + an HTTP request. + + + + + a #WebKitURIRequest + + + + + + + + the uri of the #WebKitURIRequest + + + + + a #WebKitURIRequest + + + + + + Set the URI of @request + + + + + + + a #WebKitURIRequest + + + + an URI + + + + + + The URI to which the request will be made. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Get the expected content length of the #WebKitURIResponse. It can +be 0 if the server provided an incorrect or missing Content-Length. + + + the expected content length of @response. + + + + + a #WebKitURIResponse + + + + + + Get the HTTP headers of a #WebKitURIResponse as a #SoupMessageHeaders. + + + a #SoupMessageHeaders with the HTTP headers of @response + or %NULL if @response is not an HTTP response. + + + + + a #WebKitURIResponse + + + + + + + + the MIME type of the #WebKitURIResponse + + + + + a #WebKitURIResponse + + + + + + Get the status code of the #WebKitURIResponse as returned by +the server. It will normally be a #SoupKnownStatusCode, for +example %SOUP_STATUS_OK, though the server can respond with any +unsigned integer. + + + the status code of @response + + + + + a #WebKitURIResponse + + + + + + Get the suggested filename for @response, as specified by +the 'Content-Disposition' HTTP header, or %NULL if it's not +present. + + + the suggested filename or %NULL if + the 'Content-Disposition' HTTP header is not present. + + + + + a #WebKitURIResponse + + + + + + + + the uri of the #WebKitURIResponse + + + + + a #WebKitURIResponse + + + + + + The expected content length of the response. + + + + The HTTP headers of the response, or %NULL if the response is not an HTTP response. + + + + The MIME type of the response. + + + + The status code of the response as returned by the server. + + + + The suggested filename for the URI response. + + + + The URI for which the response was made. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gets the #WebKitWebPage that is associated with the #WebKitWebEditor that can +be used to access the #WebKitDOMDocument currently loaded into it. + + + the associated #WebKitWebPage + + + + + a #WebKitWebEditor + + + + + + + + + + + + This signal is emitted for every selection change inside a #WebKitWebPage +as well as for every caret position change as the caret is a collapsed +selection. + + + + + + + + + + + + + + + + + + Get the web page of the given @page_id. + + + the #WebKitWebPage for the given @page_id, or %NULL if the + identifier doesn't correspond to an existing web page. + + + + + a #WebKitWebExtension + + + + the identifier of the #WebKitWebPage to get + + + + + + + + + + + + This signal is emitted when a new #WebKitWebPage is created in +the Web Process. + + + + + + the #WebKitWebPage created + + + + + + + + + + + + + Type definition for a function that will be called to initialize +the web extension when the web process starts. + + + + + + + a #WebKitWebExtension + + + + + + Type definition for a function that will be called to initialize +the web extensions when the web process starts, and which receives +as additional argument the user data set with +webkit_web_context_set_web_extensions_initialization_user_data(). + + + + + + + a #WebKitWebExtension + + + + a #GVariant + + + + + + + + + + + Get the #WebKitDOMNode in the coordinates of the Hit Test. + + + a #WebKitDOMNode + + + + + a #WebKitWebHitTestResult + + + + + + The #WebKitDOMNode + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Get the #WebKitDOMDocument currently loaded in @web_page + + + the #WebKitDOMDocument currently loaded, or %NULL + if no document is currently loaded. + + + + + a #WebKitWebPage + + + + + + Gets the #WebKitWebEditor of a #WebKitWebPage. + + + the #WebKitWebEditor + + + + + a #WebKitWebPage + + + + + + Get the identifier of the #WebKitWebPage + + + the identifier of @web_page + + + + + a #WebKitWebPage + + + + + + Returns the main frame of a #WebKitWebPage. + + + the #WebKitFrame that is the main frame of @web_page + + + + + a #WebKitWebPage + + + + + + Returns the current active URI of @web_page. + +You can monitor the active URI by connecting to the notify::uri +signal of @web_page. + + + the current active URI of @web_view or %NULL if nothing has been + loaded yet. + + + + + a #WebKitWebPage + + + + + + The current active URI of the #WebKitWebPage. + + + + + + + + + + Emitted when a message is sent to the console. This can be a message +produced by the use of JavaScript console API, a JavaScript exception, +a security error or other errors, warnings, debug or log messages. +The @console_message contains information of the message. + + + + + + the #WebKitConsoleMessage + + + + + + Emitted before a context menu is displayed in the UI Process to +give the application a chance to customize the proposed menu, +build its own context menu or pass user data to the UI Process. +This signal is useful when the information available in the UI Process +is not enough to build or customize the context menu, for example, to +add menu entries depending on the #WebKitDOMNode at the coordinates of the +@hit_test_result. Otherwise, it's recommended to use #WebKitWebView::context-menu +signal instead. + + %TRUE if the proposed @context_menu has been modified, or %FALSE otherwise. + + + + + the proposed #WebKitContextMenu + + + + a #WebKitWebHitTestResult + + + + + + This signal is emitted when the DOM document of a #WebKitWebPage has been +loaded. + +You can wait for this signal to get the DOM document with +webkit_web_page_get_dom_document(). + + + + + + Emitted after form elements (or form associated elements) are associated to a particular web +page. This is useful to implement form auto filling for web pages where form fields are added +dynamically. This signal might be emitted multiple times for the same web page. + +Note that this signal could be also emitted when form controls are moved between forms. In +that case, the @elements array carries the list of those elements which have moved. + +Clients should take a reference to the members of the @elements array if it is desired to +keep them alive after the signal handler returns. + , use #WebKitWebPage::form-controls-associated-for-frame instead. + + + + + + a #GPtrArray of + #WebKitDOMElement with the list of forms in the page + + + + + + + + Emitted after form elements (or form associated elements) are associated to a particular web +page. This is useful to implement form auto filling for web pages where form fields are added +dynamically. This signal might be emitted multiple times for the same web page. + +Note that this signal could be also emitted when form controls are moved between forms. In +that case, the @elements array carries the list of those elements which have moved. + +Clients should take a reference to the members of the @elements array if it is desired to +keep them alive after the signal handler returns. + + + + + + a #GPtrArray of + #WebKitDOMElement with the list of forms in the page + + + + + + the #WebKitFrame + + + + + + This signal is emitted when @request is about to be sent to +the server. This signal can be used to modify the #WebKitURIRequest +that will be sent to the server. You can also cancel the resource load +operation by connecting to this signal and returning %TRUE. + +In case of a server redirection this signal is +emitted again with the @request argument containing the new +request to be sent to the server due to the redirection and the +@redirected_response parameter containing the response +received by the server for the initial request. + +Modifications to the #WebKitURIRequest and its associated +#SoupMessageHeaders will be taken into account when the request +is sent over the network. + + %TRUE to stop other handlers from being invoked for the event. + %FALSE to continue emission of the event. + + + + + a #WebKitURIRequest + + + + a #WebKitURIResponse, or %NULL + + + + + + This signal is emitted to indicate various points during form +submission. @step indicates the current stage of form submission. + +If this signal is emitted with %WEBKIT_FORM_SUBMISSION_WILL_SEND_DOM_EVENT, +then the DOM submit event is about to be emitted. JavaScript code +may rely on the submit event to detect that the user has clicked +on a submit button, and to possibly cancel the form submission +before %WEBKIT_FORM_SUBMISSION_WILL_COMPLETE. However, beware +that, for historical reasons, the submit event is not emitted at +all if the form submission is triggered by JavaScript. For these +reasons, %WEBKIT_FORM_SUBMISSION_WILL_SEND_DOM_EVENT may not +be used to reliably detect whether a form will be submitted. +Instead, use it to detect if a user has clicked on a form's +submit button even if JavaScript later cancels the form +submission, or to read the values of the form's fields even if +JavaScript later clears certain fields before submitting. This +may be needed, for example, to implement a robust browser +password manager, as some misguided websites may use such +techniques to attempt to thwart password managers. + +If this signal is emitted with %WEBKIT_FORM_SUBMISSION_WILL_COMPLETE, +the form will imminently be submitted. It can no longer be +cancelled. This event always occurs immediately before a form is +submitted to its target, so use this event to reliably detect +when a form is submitted. This event occurs after +%WEBKIT_FORM_SUBMISSION_WILL_SEND_DOM_EVENT if that event is +emitted. + + + + + + the #WebKitDOMElement to be submitted, which will always correspond to an HTMLFormElement + + + + a #WebKitFormSubmissionEventType indicating the current +stage of form submission + + + + the #WebKitFrame containing the form to be +submitted + + + + the #WebKitFrame containing the form's target, +which may be the same as @source_frame if no target was specified + + + + names of +the form's text fields + + + + + + values +of the form's text fields + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/cairo-1.0.gir b/gir-files/cairo-1.0.gir new file mode 100644 index 0000000..b7c0e86 --- /dev/null +++ b/gir-files/cairo-1.0.gir @@ -0,0 +1,270 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/dl.sh b/gir-files/dl.sh new file mode 100755 index 0000000..62823fe --- /dev/null +++ b/gir-files/dl.sh @@ -0,0 +1,21 @@ +#!/bin/sh +set -e + +VER="eoan" + +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libatk1.0-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libgirepository1.0-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libpango1.0-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libgdk-pixbuf2.0-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libgtk-3-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libgtksourceview-3.0-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libsecret-1-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libvte-2.91-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libjavascriptcoregtk-4.0-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libsoup2.4-dev/download +./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libwebkit2gtk-4.0-dev/download + +# version 4 +./gir-dl.sh https://packages.debian.org/experimental/amd64/libgtk-4-dev/download http.us.debian.org + +./reformat.sh diff --git a/gir-files/fix.sh b/gir-files/fix.sh new file mode 100755 index 0000000..7ae9d0b --- /dev/null +++ b/gir-files/fix.sh @@ -0,0 +1,104 @@ +#!/bin/bash +set -x -e + +# Remove Int32 alias because it misses c:type, it not like anyone actually cares about it. +xmlstarlet ed -P -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 -P -L \ + -u '//*[@glib:error-domain="g-option-context-error-quark"]/@glib:error-domain' -v g-option-error-quark \ + GLib-2.0.gir + +# GtkIconSize usage +xmlstarlet ed -P -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 -P -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 -P -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 -P -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 + +# incorrectly marked as transfer-none GitLab issue #197 +xmlstarlet ed -P -L \ + -u '//_:class[@name="Binding"]/_:method[@name="unbind"]//_:instance-parameter[@name="binding"]/@transfer-ownership' -v "full" \ + GObject-2.0.gir + +# fix wrong "full" transfer ownership +xmlstarlet ed -P -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 "gint" response_id parameters with "ResponseType" +xmlstarlet ed -P -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 -P -L \ + -u '//_:constructor[@c:identifier="gtk_shortcut_label_new"]/_:return-value/@transfer-ownership' -v "none" \ + Gtk-3.0.gir Gtk-4.0.gir + +# add out annotation for functions returning GValue +xmlstarlet ed -P -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 + +xmlstarlet tr JavaScriptCore-4.0.xsl JavaScriptCore-4.0.gir | xmlstarlet fo > JavaScriptCore-4.0.gir.tmp +mv JavaScriptCore-4.0.gir.tmp JavaScriptCore-4.0.gir + +# fill in types from JavaScriptCore +xmlstarlet ed -P -L \ + -i '//_:type[not(@name) and @c:type="JSGlobalContextRef"]' -t 'attr' -n 'name' -v "JavaScriptCore.GlobalContextRef" \ + -i '//_:type[not(@name) and @c:type="JSValueRef"]' -t 'attr' -n 'name' -v "JavaScriptCore.ValueRef" \ + WebKit2WebExtension-4.0.gir WebKit2-4.0.gir + +xmlstarlet ed -P -L \ + -u '//_:constant[@name="DOM_NODE_FILTER_SHOW_ALL"]/_:type/@name' -v "guint" \ + -u '//_:constant[@name="DOM_NODE_FILTER_SHOW_ALL"]/_:type/@c:type' -v "guint" \ + WebKit2WebExtension-4.0.gir + +# remove source-position from gtk 4.0 +xmlstarlet ed -P -L \ + -d '//_:source-position' \ + Gdk-4.0.gir GdkX11-4.0.gir Graphene-1.0.gir Gsk-4.0.gir Gtk-4.0.gir + +# fix cyclic dependency on gtk 4.0 +xmlstarlet ed -P -L \ + -u '//_:callback[@name="ParseErrorFunc"]/_:parameters/_:parameter[@name="section"]/_:type[@c:type="const GtkCssSection*"]/@c:type' -v "gconstpointer" \ + -a '//_:callback[@name="ParseErrorFunc"]/_:parameters/_:parameter[@name="section"]/_:type[not(@name) and @c:type="gconstpointer"]' -type attr -n "name" -v "gconstpointer" \ + Gsk-4.0.gir diff --git a/gir-files/fontconfig-2.0.gir b/gir-files/fontconfig-2.0.gir new file mode 100644 index 0000000..d4f4749 --- /dev/null +++ b/gir-files/fontconfig-2.0.gir @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/gir-files/freetype2-2.0.gir b/gir-files/freetype2-2.0.gir new file mode 100644 index 0000000..7f06abc --- /dev/null +++ b/gir-files/freetype2-2.0.gir @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/gir-files/gir-dl.sh b/gir-files/gir-dl.sh new file mode 100755 index 0000000..639c4ab --- /dev/null +++ b/gir-files/gir-dl.sh @@ -0,0 +1,19 @@ +#!/bin/bash +set -e -u -o pipefail + +MIRRORS="$1" +echo $MIRRORS +if [ $# -lt 2 ]; then + MIRROR="mirrors.kernel.org" +else + MIRROR="$2" +fi +wget -q --show-progress -O tmp.html "$MIRRORS" +URL=`cat tmp.html | grep -oP "http://$MIRROR/[^\"]+"` +rm tmp.html +echo $URL +wget -q --show-progress -O tmp.deb "$URL" +ar x tmp.deb data.tar.xz +rm tmp.deb +tar xf data.tar.xz --strip-components 4 ./usr/share/gir-1.0 +rm data.tar.xz diff --git a/gir-files/libxml2-2.0.gir b/gir-files/libxml2-2.0.gir new file mode 100644 index 0000000..1b1c9e2 --- /dev/null +++ b/gir-files/libxml2-2.0.gir @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/reformat.sh b/gir-files/reformat.sh new file mode 100755 index 0000000..9e6b899 --- /dev/null +++ b/gir-files/reformat.sh @@ -0,0 +1,6 @@ +#!/bin/bash +set -x -e + +for file in *.gir; do + xmlstarlet ed -P -L "$file" +done diff --git a/gir-files/vivid-64.txt b/gir-files/vivid-64.txt new file mode 100644 index 0000000..064a3ff --- /dev/null +++ b/gir-files/vivid-64.txt @@ -0,0 +1,7 @@ +https://launchpad.net/~gnome3-team/+archive/ubuntu/gnome3-staging/+files/libatk1.0-dev_2.16.0-2%7Evivid0_amd64.deb +https://launchpad.net/~gnome3-team/+archive/ubuntu/gnome3-staging/+files/libgdk-pixbuf2.0-dev_2.31.4-1%7Evivid0_amd64.deb +https://launchpad.net/~gnome3-team/+archive/ubuntu/gnome3-staging/+files/libgirepository1.0-dev_1.44.0-1%7Evivid0_amd64.deb +https://launchpad.net/~gnome3-team/+archive/ubuntu/gnome3-staging/+files/libgtk-3-dev_3.16.3-0ubuntu1%7Evivid2_amd64.deb +https://launchpad.net/~gnome3-team/+archive/ubuntu/gnome3-staging/+files/libpango1.0-dev_1.36.7-1%7Eutopic1_amd64.deb +https://launchpad.net/~gnome3-team/+archive/ubuntu/gnome3-staging/+files/libsecret-1-dev_0.18.2-1%7Evivid0_amd64.deb +https://launchpad.net/~gnome3-team/+archive/ubuntu/gnome3-staging/+files/libvte-2.91-dev_0.40.2-1ubuntu1%7Evivid1_amd64.deb diff --git a/gir-files/win32-1.0.gir b/gir-files/win32-1.0.gir new file mode 100644 index 0000000..edd3381 --- /dev/null +++ b/gir-files/win32-1.0.gir @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/gir-files/xfixes-4.0.gir b/gir-files/xfixes-4.0.gir new file mode 100644 index 0000000..40eff81 --- /dev/null +++ b/gir-files/xfixes-4.0.gir @@ -0,0 +1,6 @@ + + + + + + diff --git a/gir-files/xft-2.0.gir b/gir-files/xft-2.0.gir new file mode 100644 index 0000000..fb0476c --- /dev/null +++ b/gir-files/xft-2.0.gir @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/xlib-2.0.gir b/gir-files/xlib-2.0.gir new file mode 100644 index 0000000..23243af --- /dev/null +++ b/gir-files/xlib-2.0.gir @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/xrandr-1.3.gir b/gir-files/xrandr-1.3.gir new file mode 100644 index 0000000..4def5b5 --- /dev/null +++ b/gir-files/xrandr-1.3.gir @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/lightdm-sys/Cargo.toml b/lightdm-sys/Cargo.toml new file mode 100644 index 0000000..a754a62 --- /dev/null +++ b/lightdm-sys/Cargo.toml @@ -0,0 +1,32 @@ +[package] +name = "light-dm-sys" +version = "0.0.1" +links = "light_dm" +build = "build.rs" +[package.metadata.docs.rs] +features = ["dox"] + +[lib] +name = "light_dm_sys" + +[dependencies] +libc = "0.2" + +[dependencies.gio-sys] +git = "https://github.com/gtk-rs/sys" + +[dependencies.gobject-sys] +git = "https://github.com/gtk-rs/sys" + +[dependencies.glib-sys] +git = "https://github.com/gtk-rs/sys" + +[build-dependencies] +pkg-config = "0.3.7" + +[dev-dependencies] +shell-words = "0.1.0" +tempfile = "3" + +[features] +dox = [] diff --git a/lightdm-sys/Gir.toml b/lightdm-sys/Gir.toml new file mode 100644 index 0000000..b75156c --- /dev/null +++ b/lightdm-sys/Gir.toml @@ -0,0 +1,9 @@ +[options] +library = "LightDM" +version = "1" +target_path = "." +min_cfg_version = "1" +work_mode = "sys" +girs_dir = "../gir-files/" + +external_libraries = ["Gio", "GObject", "GLib"] diff --git a/lightdm-sys/build.rs b/lightdm-sys/build.rs new file mode 100644 index 0000000..a2c2735 --- /dev/null +++ b/lightdm-sys/build.rs @@ -0,0 +1,82 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir @ 2abca11) +// from gir-files (https://github.com/gtk-rs/gir-files @ b89185a) +// DO NOT EDIT + +#[cfg(not(feature = "dox"))] +extern crate pkg_config; + +#[cfg(not(feature = "dox"))] +use pkg_config::{Config, Error}; +#[cfg(not(feature = "dox"))] +use std::env; +#[cfg(not(feature = "dox"))] +use std::io; +#[cfg(not(feature = "dox"))] +use std::io::prelude::*; +#[cfg(not(feature = "dox"))] +use std::process; + +#[cfg(feature = "dox")] +fn main() {} // prevent linking libraries to avoid documentation failure + +#[cfg(not(feature = "dox"))] +fn main() { + if let Err(s) = find() { + let _ = writeln!(io::stderr(), "{}", s); + process::exit(1); + } +} + +#[cfg(not(feature = "dox"))] +fn find() -> Result<(), Error> { + let package_name = "liblightdm-gobject-1"; + let shared_libs = ["lightdm-gobject-1"]; + let version = { "1" }; + + if let Ok(inc_dir) = env::var("GTK_INCLUDE_DIR") { + println!("cargo:include={}", inc_dir); + } + if let Ok(lib_dir) = env::var("GTK_LIB_DIR") { + for lib_ in shared_libs.iter() { + println!("cargo:rustc-link-lib=dylib={}", lib_); + } + println!("cargo:rustc-link-search=native={}", lib_dir); + return Ok(()); + } + + let target = env::var("TARGET").expect("TARGET environment variable doesn't exist"); + let hardcode_shared_libs = target.contains("windows"); + + let mut config = Config::new(); + config.atleast_version(version); + config.print_system_libs(false); + if hardcode_shared_libs { + config.cargo_metadata(false); + } + match config.probe(package_name) { + Ok(library) => { + if let Ok(paths) = std::env::join_paths(library.include_paths) { + println!("cargo:include={}", paths.to_string_lossy()); + } + if hardcode_shared_libs { + for lib_ in shared_libs.iter() { + println!("cargo:rustc-link-lib=dylib={}", lib_); + } + for path in library.link_paths.iter() { + println!( + "cargo:rustc-link-search=native={}", + path.to_str().expect("library path doesn't exist") + ); + } + } + Ok(()) + } + Err(Error::EnvNoPkgConfig(_)) | Err(Error::Command { .. }) => { + for lib_ in shared_libs.iter() { + println!("cargo:rustc-link-lib=dylib={}", lib_); + } + Ok(()) + } + Err(err) => Err(err), + } +} diff --git a/lightdm-sys/src/lib.rs b/lightdm-sys/src/lib.rs new file mode 100644 index 0000000..5e2879e --- /dev/null +++ b/lightdm-sys/src/lib.rs @@ -0,0 +1,534 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir @ 2abca11) +// from gir-files (https://github.com/gtk-rs/gir-files @ b89185a) +// DO NOT EDIT + +#![allow(non_camel_case_types, non_upper_case_globals, non_snake_case)] +#![allow( + clippy::approx_constant, + clippy::type_complexity, + clippy::unreadable_literal +)] + +extern crate gio_sys as gio; +extern crate glib_sys as glib; +extern crate gobject_sys as gobject; +extern crate libc; + +#[allow(unused_imports)] +use libc::{ + c_char, c_double, c_float, c_int, c_long, c_short, c_uchar, c_uint, c_ulong, c_ushort, c_void, + intptr_t, size_t, ssize_t, time_t, uintptr_t, FILE, +}; + +#[allow(unused_imports)] +use glib::{gboolean, gconstpointer, gpointer, GType}; + +// Enums +pub type LightDMGreeterError = c_int; +pub const LIGHTDM_GREETER_ERROR_COMMUNICATION_ERROR: LightDMGreeterError = 0; +pub const LIGHTDM_GREETER_ERROR_CONNECTION_FAILED: LightDMGreeterError = 1; +pub const LIGHTDM_GREETER_ERROR_SESSION_FAILED: LightDMGreeterError = 2; +pub const LIGHTDM_GREETER_ERROR_NO_AUTOLOGIN: LightDMGreeterError = 3; +pub const LIGHTDM_GREETER_ERROR_INVALID_USER: LightDMGreeterError = 4; + +pub type LightDMMessageType = c_int; +pub const LIGHTDM_MESSAGE_TYPE_INFO: LightDMMessageType = 0; +pub const LIGHTDM_MESSAGE_TYPE_ERROR: LightDMMessageType = 1; + +pub type LightDMPromptType = c_int; +pub const LIGHTDM_PROMPT_TYPE_QUESTION: LightDMPromptType = 0; +pub const LIGHTDM_PROMPT_TYPE_SECRET: LightDMPromptType = 1; + +// Constants +pub const LIGHTDM_GREETER_SIGNAL_AUTHENTICATION_COMPLETE: *const c_char = + b"authentication-complete\0" as *const u8 as *const c_char; +pub const LIGHTDM_GREETER_SIGNAL_AUTOLOGIN_TIMER_EXPIRED: *const c_char = + b"autologin-timer-expired\0" as *const u8 as *const c_char; +pub const LIGHTDM_GREETER_SIGNAL_IDLE: *const c_char = b"idle\0" as *const u8 as *const c_char; +pub const LIGHTDM_GREETER_SIGNAL_RESET: *const c_char = b"reset\0" as *const u8 as *const c_char; +pub const LIGHTDM_GREETER_SIGNAL_SHOW_MESSAGE: *const c_char = + b"show-message\0" as *const u8 as *const c_char; +pub const LIGHTDM_GREETER_SIGNAL_SHOW_PROMPT: *const c_char = + b"show-prompt\0" as *const u8 as *const c_char; +pub const LIGHTDM_SIGNAL_USER_CHANGED: *const c_char = b"changed\0" as *const u8 as *const c_char; +pub const LIGHTDM_USER_LIST_SIGNAL_USER_ADDED: *const c_char = + b"user-added\0" as *const u8 as *const c_char; +pub const LIGHTDM_USER_LIST_SIGNAL_USER_CHANGED: *const c_char = + b"user-changed\0" as *const u8 as *const c_char; +pub const LIGHTDM_USER_LIST_SIGNAL_USER_REMOVED: *const c_char = + b"user-removed\0" as *const u8 as *const c_char; + +// Records +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMGreeterClass { + pub parent_class: gobject::GObjectClass, + pub show_message: + Option, + pub show_prompt: + Option, + pub authentication_complete: Option, + pub autologin_timer_expired: Option, + pub idle: Option, + pub reset: Option, + pub reserved1: Option, + pub reserved2: Option, + pub reserved3: Option, + pub reserved4: Option, +} + +impl ::std::fmt::Debug for LightDMGreeterClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMGreeterClass @ {:?}", self as *const _)) + .field("show_message", &self.show_message) + .field("show_prompt", &self.show_prompt) + .field("authentication_complete", &self.authentication_complete) + .field("autologin_timer_expired", &self.autologin_timer_expired) + .field("idle", &self.idle) + .field("reset", &self.reset) + .field("reserved1", &self.reserved1) + .field("reserved2", &self.reserved2) + .field("reserved3", &self.reserved3) + .field("reserved4", &self.reserved4) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMLanguageClass { + pub parent_class: gobject::GObjectClass, + pub reserved1: Option, + pub reserved2: Option, + pub reserved3: Option, + pub reserved4: Option, + pub reserved5: Option, + pub reserved6: Option, +} + +impl ::std::fmt::Debug for LightDMLanguageClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMLanguageClass @ {:?}", self as *const _)) + .field("reserved1", &self.reserved1) + .field("reserved2", &self.reserved2) + .field("reserved3", &self.reserved3) + .field("reserved4", &self.reserved4) + .field("reserved5", &self.reserved5) + .field("reserved6", &self.reserved6) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMLayoutClass { + pub parent_class: gobject::GObjectClass, + pub reserved1: Option, + pub reserved2: Option, + pub reserved3: Option, + pub reserved4: Option, + pub reserved5: Option, + pub reserved6: Option, +} + +impl ::std::fmt::Debug for LightDMLayoutClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMLayoutClass @ {:?}", self as *const _)) + .field("reserved1", &self.reserved1) + .field("reserved2", &self.reserved2) + .field("reserved3", &self.reserved3) + .field("reserved4", &self.reserved4) + .field("reserved5", &self.reserved5) + .field("reserved6", &self.reserved6) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMSessionClass { + pub parent_class: gobject::GObjectClass, + pub reserved1: Option, + pub reserved2: Option, + pub reserved3: Option, + pub reserved4: Option, + pub reserved5: Option, + pub reserved6: Option, +} + +impl ::std::fmt::Debug for LightDMSessionClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMSessionClass @ {:?}", self as *const _)) + .field("reserved1", &self.reserved1) + .field("reserved2", &self.reserved2) + .field("reserved3", &self.reserved3) + .field("reserved4", &self.reserved4) + .field("reserved5", &self.reserved5) + .field("reserved6", &self.reserved6) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMUserClass { + pub parent_class: gobject::GObjectClass, + pub changed: Option, + pub reserved1: Option, + pub reserved2: Option, + pub reserved3: Option, + pub reserved4: Option, + pub reserved5: Option, + pub reserved6: Option, +} + +impl ::std::fmt::Debug for LightDMUserClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMUserClass @ {:?}", self as *const _)) + .field("changed", &self.changed) + .field("reserved1", &self.reserved1) + .field("reserved2", &self.reserved2) + .field("reserved3", &self.reserved3) + .field("reserved4", &self.reserved4) + .field("reserved5", &self.reserved5) + .field("reserved6", &self.reserved6) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMUserListClass { + pub parent_class: gobject::GObjectClass, + pub user_added: Option, + pub user_changed: Option, + pub user_removed: Option, + pub reserved1: Option, + pub reserved2: Option, + pub reserved3: Option, + pub reserved4: Option, + pub reserved5: Option, + pub reserved6: Option, +} + +impl ::std::fmt::Debug for LightDMUserListClass { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMUserListClass @ {:?}", self as *const _)) + .field("user_added", &self.user_added) + .field("user_changed", &self.user_changed) + .field("user_removed", &self.user_removed) + .field("reserved1", &self.reserved1) + .field("reserved2", &self.reserved2) + .field("reserved3", &self.reserved3) + .field("reserved4", &self.reserved4) + .field("reserved5", &self.reserved5) + .field("reserved6", &self.reserved6) + .finish() + } +} + +// Classes +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMGreeter { + pub parent_instance: gobject::GObject, +} + +impl ::std::fmt::Debug for LightDMGreeter { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMGreeter @ {:?}", self as *const _)) + .field("parent_instance", &self.parent_instance) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMLanguage { + pub parent_instance: gobject::GObject, +} + +impl ::std::fmt::Debug for LightDMLanguage { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMLanguage @ {:?}", self as *const _)) + .field("parent_instance", &self.parent_instance) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMLayout { + pub parent_instance: gobject::GObject, +} + +impl ::std::fmt::Debug for LightDMLayout { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMLayout @ {:?}", self as *const _)) + .field("parent_instance", &self.parent_instance) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMSession { + pub parent_instance: gobject::GObject, +} + +impl ::std::fmt::Debug for LightDMSession { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMSession @ {:?}", self as *const _)) + .field("parent_instance", &self.parent_instance) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMUser { + pub parent_instance: gobject::GObject, +} + +impl ::std::fmt::Debug for LightDMUser { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMUser @ {:?}", self as *const _)) + .field("parent_instance", &self.parent_instance) + .finish() + } +} + +#[repr(C)] +#[derive(Copy, Clone)] +pub struct LightDMUserList { + pub parent_instance: gobject::GObject, +} + +impl ::std::fmt::Debug for LightDMUserList { + fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { + f.debug_struct(&format!("LightDMUserList @ {:?}", self as *const _)) + .field("parent_instance", &self.parent_instance) + .finish() + } +} + +extern "C" { + + //========================================================================= + // LightDMGreeterError + //========================================================================= + pub fn lightdm_greeter_error_get_type() -> GType; + pub fn lightdm_greeter_error_quark() -> glib::GQuark; + + //========================================================================= + // LightDMMessageType + //========================================================================= + pub fn lightdm_message_type_get_type() -> GType; + + //========================================================================= + // LightDMPromptType + //========================================================================= + pub fn lightdm_prompt_type_get_type() -> GType; + + //========================================================================= + // LightDMGreeter + //========================================================================= + pub fn lightdm_greeter_get_type() -> GType; + pub fn lightdm_greeter_new() -> *mut LightDMGreeter; + pub fn lightdm_greeter_authenticate( + greeter: *mut LightDMGreeter, + username: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_authenticate_as_guest( + greeter: *mut LightDMGreeter, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_authenticate_autologin( + greeter: *mut LightDMGreeter, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_authenticate_remote( + greeter: *mut LightDMGreeter, + session: *const c_char, + username: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_cancel_authentication( + greeter: *mut LightDMGreeter, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_cancel_autologin(greeter: *mut LightDMGreeter); + pub fn lightdm_greeter_connect_sync( + greeter: *mut LightDMGreeter, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_connect_to_daemon( + greeter: *mut LightDMGreeter, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + pub fn lightdm_greeter_connect_to_daemon_finish( + greeter: *mut LightDMGreeter, + result: *mut gio::GAsyncResult, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_connect_to_daemon_sync( + greeter: *mut LightDMGreeter, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_ensure_shared_data_dir( + greeter: *mut LightDMGreeter, + username: *const c_char, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + pub fn lightdm_greeter_ensure_shared_data_dir_finish( + greeter: *mut LightDMGreeter, + result: *mut gio::GAsyncResult, + error: *mut *mut glib::GError, + ) -> *mut c_char; + pub fn lightdm_greeter_ensure_shared_data_dir_sync( + greeter: *mut LightDMGreeter, + username: *const c_char, + error: *mut *mut glib::GError, + ) -> *mut c_char; + pub fn lightdm_greeter_get_authentication_user(greeter: *mut LightDMGreeter) -> *const c_char; + pub fn lightdm_greeter_get_autologin_guest_hint(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_get_autologin_session_hint( + greeter: *mut LightDMGreeter, + ) -> *const c_char; + pub fn lightdm_greeter_get_autologin_timeout_hint(greeter: *mut LightDMGreeter) -> c_int; + pub fn lightdm_greeter_get_autologin_user_hint(greeter: *mut LightDMGreeter) -> *const c_char; + pub fn lightdm_greeter_get_default_session_hint(greeter: *mut LightDMGreeter) -> *const c_char; + pub fn lightdm_greeter_get_has_guest_account_hint(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_get_hide_users_hint(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_get_hint( + greeter: *mut LightDMGreeter, + name: *const c_char, + ) -> *const c_char; + pub fn lightdm_greeter_get_in_authentication(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_get_is_authenticated(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_get_lock_hint(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_get_select_guest_hint(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_get_select_user_hint(greeter: *mut LightDMGreeter) -> *const c_char; + pub fn lightdm_greeter_get_show_manual_login_hint(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_get_show_remote_login_hint(greeter: *mut LightDMGreeter) -> gboolean; + pub fn lightdm_greeter_respond( + greeter: *mut LightDMGreeter, + response: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_set_language( + greeter: *mut LightDMGreeter, + language: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_set_resettable(greeter: *mut LightDMGreeter, resettable: gboolean); + pub fn lightdm_greeter_start_session( + greeter: *mut LightDMGreeter, + session: *const c_char, + cancellable: *mut gio::GCancellable, + callback: gio::GAsyncReadyCallback, + user_data: gpointer, + ); + pub fn lightdm_greeter_start_session_finish( + greeter: *mut LightDMGreeter, + result: *mut gio::GAsyncResult, + error: *mut *mut glib::GError, + ) -> gboolean; + pub fn lightdm_greeter_start_session_sync( + greeter: *mut LightDMGreeter, + session: *const c_char, + error: *mut *mut glib::GError, + ) -> gboolean; + + //========================================================================= + // LightDMLanguage + //========================================================================= + pub fn lightdm_language_get_type() -> GType; + pub fn lightdm_language_get_code(language: *mut LightDMLanguage) -> *const c_char; + pub fn lightdm_language_get_name(language: *mut LightDMLanguage) -> *const c_char; + pub fn lightdm_language_get_territory(language: *mut LightDMLanguage) -> *const c_char; + pub fn lightdm_language_matches( + language: *mut LightDMLanguage, + code: *const c_char, + ) -> gboolean; + + //========================================================================= + // LightDMLayout + //========================================================================= + pub fn lightdm_layout_get_type() -> GType; + pub fn lightdm_layout_get_description(layout: *mut LightDMLayout) -> *const c_char; + pub fn lightdm_layout_get_name(layout: *mut LightDMLayout) -> *const c_char; + pub fn lightdm_layout_get_short_description(layout: *mut LightDMLayout) -> *const c_char; + + //========================================================================= + // LightDMSession + //========================================================================= + pub fn lightdm_session_get_type() -> GType; + pub fn lightdm_session_get_comment(session: *mut LightDMSession) -> *const c_char; + pub fn lightdm_session_get_key(session: *mut LightDMSession) -> *const c_char; + pub fn lightdm_session_get_name(session: *mut LightDMSession) -> *const c_char; + pub fn lightdm_session_get_session_type(session: *mut LightDMSession) -> *const c_char; + + //========================================================================= + // LightDMUser + //========================================================================= + pub fn lightdm_user_get_type() -> GType; + pub fn lightdm_user_get_background(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_display_name(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_has_messages(user: *mut LightDMUser) -> gboolean; + pub fn lightdm_user_get_home_directory(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_image(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_is_locked(user: *mut LightDMUser) -> gboolean; + pub fn lightdm_user_get_language(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_layout(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_layouts(user: *mut LightDMUser) -> *const *const c_char; + pub fn lightdm_user_get_logged_in(user: *mut LightDMUser) -> gboolean; + pub fn lightdm_user_get_name(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_real_name(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_session(user: *mut LightDMUser) -> *const c_char; + pub fn lightdm_user_get_uid(user: *mut LightDMUser) -> c_uint; + + //========================================================================= + // LightDMUserList + //========================================================================= + pub fn lightdm_user_list_get_type() -> GType; + pub fn lightdm_user_list_get_instance() -> *mut LightDMUserList; + pub fn lightdm_user_list_get_length(user_list: *mut LightDMUserList) -> c_int; + pub fn lightdm_user_list_get_user_by_name( + user_list: *mut LightDMUserList, + username: *const c_char, + ) -> *mut LightDMUser; + pub fn lightdm_user_list_get_users(user_list: *mut LightDMUserList) -> *mut glib::GList; + + //========================================================================= + // Other functions + //========================================================================= + pub fn lightdm_get_can_hibernate() -> gboolean; + pub fn lightdm_get_can_restart() -> gboolean; + pub fn lightdm_get_can_shutdown() -> gboolean; + pub fn lightdm_get_can_suspend() -> gboolean; + pub fn lightdm_get_hostname() -> *const c_char; + pub fn lightdm_get_language() -> *mut LightDMLanguage; + pub fn lightdm_get_languages() -> *mut glib::GList; + pub fn lightdm_get_layout() -> *mut LightDMLayout; + pub fn lightdm_get_layouts() -> *mut glib::GList; + pub fn lightdm_get_motd() -> *mut c_char; + pub fn lightdm_get_os_id() -> *const c_char; + pub fn lightdm_get_os_name() -> *const c_char; + pub fn lightdm_get_os_pretty_name() -> *const c_char; + pub fn lightdm_get_os_version() -> *const c_char; + pub fn lightdm_get_os_version_id() -> *const c_char; + pub fn lightdm_get_remote_sessions() -> *mut glib::GList; + pub fn lightdm_get_sessions() -> *mut glib::GList; + pub fn lightdm_hibernate(error: *mut *mut glib::GError) -> gboolean; + pub fn lightdm_restart(error: *mut *mut glib::GError) -> gboolean; + pub fn lightdm_set_layout(layout: *mut LightDMLayout); + pub fn lightdm_shutdown(error: *mut *mut glib::GError) -> gboolean; + pub fn lightdm_suspend(error: *mut *mut glib::GError) -> gboolean; + +} diff --git a/lightdm-sys/tests/abi.rs b/lightdm-sys/tests/abi.rs new file mode 100644 index 0000000..346cf14 --- /dev/null +++ b/lightdm-sys/tests/abi.rs @@ -0,0 +1,388 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir @ 2abca11) +// from gir-files (https://github.com/gtk-rs/gir-files @ b89185a) +// DO NOT EDIT + +extern crate light_dm_sys; +extern crate shell_words; +extern crate tempfile; +use light_dm_sys::*; +use std::env; +use std::error::Error; +use std::mem::{align_of, size_of}; +use std::path::Path; +use std::process::Command; +use std::str; +use tempfile::Builder; + +static PACKAGES: &[&str] = &["liblightdm-gobject-1"]; + +#[derive(Clone, Debug)] +struct Compiler { + pub args: Vec, +} + +impl Compiler { + pub fn new() -> Result> { + let mut args = get_var("CC", "cc")?; + args.push("-Wno-deprecated-declarations".to_owned()); + // For %z support in printf when using MinGW. + args.push("-D__USE_MINGW_ANSI_STDIO".to_owned()); + args.extend(get_var("CFLAGS", "")?); + args.extend(get_var("CPPFLAGS", "")?); + args.extend(pkg_config_cflags(PACKAGES)?); + Ok(Compiler { args }) + } + + pub fn define<'a, V: Into>>(&mut self, var: &str, val: V) { + let arg = match val.into() { + None => format!("-D{}", var), + Some(val) => format!("-D{}={}", var, val), + }; + self.args.push(arg); + } + + pub fn compile(&self, src: &Path, out: &Path) -> Result<(), Box> { + let mut cmd = self.to_command(); + cmd.arg(src); + cmd.arg("-o"); + cmd.arg(out); + let status = cmd.spawn()?.wait()?; + if !status.success() { + return Err(format!("compilation command {:?} failed, {}", &cmd, status).into()); + } + Ok(()) + } + + fn to_command(&self) -> Command { + let mut cmd = Command::new(&self.args[0]); + cmd.args(&self.args[1..]); + cmd + } +} + +fn get_var(name: &str, default: &str) -> Result, Box> { + match env::var(name) { + Ok(value) => Ok(shell_words::split(&value)?), + Err(env::VarError::NotPresent) => Ok(shell_words::split(default)?), + Err(err) => Err(format!("{} {}", name, err).into()), + } +} + +fn pkg_config_cflags(packages: &[&str]) -> Result, Box> { + if packages.is_empty() { + return Ok(Vec::new()); + } + let mut cmd = Command::new("pkg-config"); + cmd.arg("--cflags"); + cmd.args(packages); + let out = cmd.output()?; + if !out.status.success() { + return Err(format!("command {:?} returned {}", &cmd, out.status).into()); + } + let stdout = str::from_utf8(&out.stdout)?; + Ok(shell_words::split(stdout.trim())?) +} + +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +struct Layout { + size: usize, + alignment: usize, +} + +#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)] +struct Results { + /// Number of successfully completed tests. + passed: usize, + /// Total number of failed tests (including those that failed to compile). + failed: usize, + /// Number of tests that failed to compile. + failed_to_compile: usize, +} + +impl Results { + fn record_passed(&mut self) { + self.passed += 1; + } + fn record_failed(&mut self) { + self.failed += 1; + } + fn record_failed_to_compile(&mut self) { + self.failed += 1; + self.failed_to_compile += 1; + } + fn summary(&self) -> String { + format!( + "{} passed; {} failed (compilation errors: {})", + self.passed, self.failed, self.failed_to_compile + ) + } + fn expect_total_success(&self) { + if self.failed == 0 { + println!("OK: {}", self.summary()); + } else { + panic!("FAILED: {}", self.summary()); + }; + } +} + +#[test] +fn cross_validate_constants_with_c() { + let tmpdir = Builder::new() + .prefix("abi") + .tempdir() + .expect("temporary directory"); + let cc = Compiler::new().expect("configured compiler"); + + assert_eq!( + "1", + get_c_value(tmpdir.path(), &cc, "1").expect("C constant"), + "failed to obtain correct constant value for 1" + ); + + let mut results: Results = Default::default(); + for (i, &(name, rust_value)) in RUST_CONSTANTS.iter().enumerate() { + match get_c_value(tmpdir.path(), &cc, name) { + Err(e) => { + results.record_failed_to_compile(); + eprintln!("{}", e); + } + Ok(ref c_value) => { + if rust_value == c_value { + results.record_passed(); + } else { + results.record_failed(); + eprintln!( + "Constant value mismatch for {}\nRust: {:?}\nC: {:?}", + name, rust_value, c_value + ); + } + } + }; + if (i + 1) % 25 == 0 { + println!("constants ... {}", results.summary()); + } + } + results.expect_total_success(); +} + +#[test] +fn cross_validate_layout_with_c() { + let tmpdir = Builder::new() + .prefix("abi") + .tempdir() + .expect("temporary directory"); + let cc = Compiler::new().expect("configured compiler"); + + assert_eq!( + Layout { + size: 1, + alignment: 1 + }, + get_c_layout(tmpdir.path(), &cc, "char").expect("C layout"), + "failed to obtain correct layout for char type" + ); + + let mut results: Results = Default::default(); + for (i, &(name, rust_layout)) in RUST_LAYOUTS.iter().enumerate() { + match get_c_layout(tmpdir.path(), &cc, name) { + Err(e) => { + results.record_failed_to_compile(); + eprintln!("{}", e); + } + Ok(c_layout) => { + if rust_layout == c_layout { + results.record_passed(); + } else { + results.record_failed(); + eprintln!( + "Layout mismatch for {}\nRust: {:?}\nC: {:?}", + name, rust_layout, &c_layout + ); + } + } + }; + if (i + 1) % 25 == 0 { + println!("layout ... {}", results.summary()); + } + } + results.expect_total_success(); +} + +fn get_c_layout(dir: &Path, cc: &Compiler, name: &str) -> Result> { + let exe = dir.join("layout"); + let mut cc = cc.clone(); + cc.define("ABI_TYPE_NAME", name); + cc.compile(Path::new("tests/layout.c"), &exe)?; + + let mut abi_cmd = Command::new(exe); + let output = abi_cmd.output()?; + if !output.status.success() { + return Err(format!("command {:?} failed, {:?}", &abi_cmd, &output).into()); + } + + let stdout = str::from_utf8(&output.stdout)?; + let mut words = stdout.trim().split_whitespace(); + let size = words.next().unwrap().parse().unwrap(); + let alignment = words.next().unwrap().parse().unwrap(); + Ok(Layout { size, alignment }) +} + +fn get_c_value(dir: &Path, cc: &Compiler, name: &str) -> Result> { + let exe = dir.join("constant"); + let mut cc = cc.clone(); + cc.define("ABI_CONSTANT_NAME", name); + cc.compile(Path::new("tests/constant.c"), &exe)?; + + let mut abi_cmd = Command::new(exe); + let output = abi_cmd.output()?; + if !output.status.success() { + return Err(format!("command {:?} failed, {:?}", &abi_cmd, &output).into()); + } + + let output = str::from_utf8(&output.stdout)?.trim(); + if !output.starts_with("###gir test###") || !output.ends_with("###gir test###") { + return Err(format!( + "command {:?} return invalid output, {:?}", + &abi_cmd, &output + ) + .into()); + } + + Ok(String::from(&output[14..(output.len() - 14)])) +} + +const RUST_LAYOUTS: &[(&str, Layout)] = &[ + ( + "LightDMGreeter", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMGreeterClass", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMGreeterError", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMLanguage", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMLanguageClass", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMLayout", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMLayoutClass", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMMessageType", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMPromptType", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMSession", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMSessionClass", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMUser", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMUserClass", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMUserList", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), + ( + "LightDMUserListClass", + Layout { + size: size_of::(), + alignment: align_of::(), + }, + ), +]; + +const RUST_CONSTANTS: &[(&str, &str)] = &[ + ("(gint) LIGHTDM_GREETER_ERROR_COMMUNICATION_ERROR", "0"), + ("(gint) LIGHTDM_GREETER_ERROR_CONNECTION_FAILED", "1"), + ("(gint) LIGHTDM_GREETER_ERROR_INVALID_USER", "4"), + ("(gint) LIGHTDM_GREETER_ERROR_NO_AUTOLOGIN", "3"), + ("(gint) LIGHTDM_GREETER_ERROR_SESSION_FAILED", "2"), + ( + "LIGHTDM_GREETER_SIGNAL_AUTHENTICATION_COMPLETE", + "authentication-complete", + ), + ( + "LIGHTDM_GREETER_SIGNAL_AUTOLOGIN_TIMER_EXPIRED", + "autologin-timer-expired", + ), + ("LIGHTDM_GREETER_SIGNAL_IDLE", "idle"), + ("LIGHTDM_GREETER_SIGNAL_RESET", "reset"), + ("LIGHTDM_GREETER_SIGNAL_SHOW_MESSAGE", "show-message"), + ("LIGHTDM_GREETER_SIGNAL_SHOW_PROMPT", "show-prompt"), + ("(gint) LIGHTDM_MESSAGE_TYPE_ERROR", "1"), + ("(gint) LIGHTDM_MESSAGE_TYPE_INFO", "0"), + ("(gint) LIGHTDM_PROMPT_TYPE_QUESTION", "0"), + ("(gint) LIGHTDM_PROMPT_TYPE_SECRET", "1"), + ("LIGHTDM_SIGNAL_USER_CHANGED", "changed"), + ("LIGHTDM_USER_LIST_SIGNAL_USER_ADDED", "user-added"), + ("LIGHTDM_USER_LIST_SIGNAL_USER_CHANGED", "user-changed"), + ("LIGHTDM_USER_LIST_SIGNAL_USER_REMOVED", "user-removed"), +]; diff --git a/lightdm-sys/tests/constant.c b/lightdm-sys/tests/constant.c new file mode 100644 index 0000000..4428439 --- /dev/null +++ b/lightdm-sys/tests/constant.c @@ -0,0 +1,27 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir @ 2abca11) +// from gir-files (https://github.com/gtk-rs/gir-files @ b89185a) +// DO NOT EDIT + +#include "manual.h" +#include + +int main() { + printf(_Generic((ABI_CONSTANT_NAME), + char *: "###gir test###%s###gir test###\n", + const char *: "###gir test###%s###gir test###\n", + char: "###gir test###%c###gir test###\n", + signed char: "###gir test###%hhd###gir test###\n", + unsigned char: "###gir test###%hhu###gir test###\n", + short int: "###gir test###%hd###gir test###\n", + unsigned short int: "###gir test###%hu###gir test###\n", + int: "###gir test###%d###gir test###\n", + unsigned int: "###gir test###%u###gir test###\n", + long: "###gir test###%ld###gir test###\n", + unsigned long: "###gir test###%lu###gir test###\n", + long long: "###gir test###%lld###gir test###\n", + unsigned long long: "###gir test###%llu###gir test###\n", + double: "###gir test###%f###gir test###\n", + long double: "###gir test###%ld###gir test###\n"), + ABI_CONSTANT_NAME); + return 0; +} diff --git a/lightdm-sys/tests/layout.c b/lightdm-sys/tests/layout.c new file mode 100644 index 0000000..18f8e36 --- /dev/null +++ b/lightdm-sys/tests/layout.c @@ -0,0 +1,12 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir @ 2abca11) +// from gir-files (https://github.com/gtk-rs/gir-files @ b89185a) +// DO NOT EDIT + +#include "manual.h" +#include +#include + +int main() { + printf("%zu\n%zu", sizeof(ABI_TYPE_NAME), alignof(ABI_TYPE_NAME)); + return 0; +} diff --git a/lightdm-sys/tests/manual.h b/lightdm-sys/tests/manual.h new file mode 100644 index 0000000..341736a --- /dev/null +++ b/lightdm-sys/tests/manual.h @@ -0,0 +1,3 @@ +// Feel free to edit this file, it won't be regenerated by gir generator unless removed. + +#include diff --git a/src/auto/constants.rs b/src/auto/constants.rs new file mode 100644 index 0000000..7918ca0 --- /dev/null +++ b/src/auto/constants.rs @@ -0,0 +1,67 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use light_dm_sys; +use std::ffi::CStr; + +pub static GREETER_SIGNAL_AUTHENTICATION_COMPLETE: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_GREETER_SIGNAL_AUTHENTICATION_COMPLETE) + .to_str() + .unwrap() + }); +pub static GREETER_SIGNAL_AUTOLOGIN_TIMER_EXPIRED: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_GREETER_SIGNAL_AUTOLOGIN_TIMER_EXPIRED) + .to_str() + .unwrap() + }); +pub static GREETER_SIGNAL_IDLE: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_GREETER_SIGNAL_IDLE) + .to_str() + .unwrap() + }); +pub static GREETER_SIGNAL_RESET: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_GREETER_SIGNAL_RESET) + .to_str() + .unwrap() + }); +pub static GREETER_SIGNAL_SHOW_MESSAGE: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_GREETER_SIGNAL_SHOW_MESSAGE) + .to_str() + .unwrap() + }); +pub static GREETER_SIGNAL_SHOW_PROMPT: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_GREETER_SIGNAL_SHOW_PROMPT) + .to_str() + .unwrap() + }); +pub static SIGNAL_USER_CHANGED: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_SIGNAL_USER_CHANGED) + .to_str() + .unwrap() + }); +pub static USER_LIST_SIGNAL_USER_ADDED: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_USER_LIST_SIGNAL_USER_ADDED) + .to_str() + .unwrap() + }); +pub static USER_LIST_SIGNAL_USER_CHANGED: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_USER_LIST_SIGNAL_USER_CHANGED) + .to_str() + .unwrap() + }); +pub static USER_LIST_SIGNAL_USER_REMOVED: once_cell::sync::Lazy<&'static str> = + once_cell::sync::Lazy::new(|| unsafe { + CStr::from_ptr(light_dm_sys::LIGHTDM_USER_LIST_SIGNAL_USER_REMOVED) + .to_str() + .unwrap() + }); diff --git a/src/auto/enums.rs b/src/auto/enums.rs new file mode 100644 index 0000000..7a7c7bd --- /dev/null +++ b/src/auto/enums.rs @@ -0,0 +1,264 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use glib::error::ErrorDomain; +use glib::translate::*; +use glib::value::FromValue; +use glib::value::FromValueOptional; +use glib::value::SetValue; +use glib::value::Value; +use glib::Quark; +use glib::StaticType; +use glib::Type; +use gobject_sys; +use light_dm_sys; +use std::fmt; + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] +#[non_exhaustive] +pub enum GreeterError { + CommunicationError, + ConnectionFailed, + SessionFailed, + NoAutologin, + InvalidUser, + #[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for GreeterError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!( + f, + "GreeterError::{}", + match *self { + GreeterError::CommunicationError => "CommunicationError", + GreeterError::ConnectionFailed => "ConnectionFailed", + GreeterError::SessionFailed => "SessionFailed", + GreeterError::NoAutologin => "NoAutologin", + GreeterError::InvalidUser => "InvalidUser", + _ => "Unknown", + } + ) + } +} + +#[doc(hidden)] +impl ToGlib for GreeterError { + type GlibType = light_dm_sys::LightDMGreeterError; + + fn to_glib(&self) -> light_dm_sys::LightDMGreeterError { + match *self { + GreeterError::CommunicationError => { + light_dm_sys::LIGHTDM_GREETER_ERROR_COMMUNICATION_ERROR + } + GreeterError::ConnectionFailed => light_dm_sys::LIGHTDM_GREETER_ERROR_CONNECTION_FAILED, + GreeterError::SessionFailed => light_dm_sys::LIGHTDM_GREETER_ERROR_SESSION_FAILED, + GreeterError::NoAutologin => light_dm_sys::LIGHTDM_GREETER_ERROR_NO_AUTOLOGIN, + GreeterError::InvalidUser => light_dm_sys::LIGHTDM_GREETER_ERROR_INVALID_USER, + GreeterError::__Unknown(value) => value, + } + } +} + +#[doc(hidden)] +impl FromGlib for GreeterError { + fn from_glib(value: light_dm_sys::LightDMGreeterError) -> Self { + match value { + 0 => GreeterError::CommunicationError, + 1 => GreeterError::ConnectionFailed, + 2 => GreeterError::SessionFailed, + 3 => GreeterError::NoAutologin, + 4 => GreeterError::InvalidUser, + value => GreeterError::__Unknown(value), + } + } +} + +impl ErrorDomain for GreeterError { + fn domain() -> Quark { + unsafe { from_glib(light_dm_sys::lightdm_greeter_error_quark()) } + } + + fn code(self) -> i32 { + self.to_glib() + } + + fn from(code: i32) -> Option { + match code { + 0 => Some(GreeterError::CommunicationError), + 1 => Some(GreeterError::ConnectionFailed), + 2 => Some(GreeterError::SessionFailed), + 3 => Some(GreeterError::NoAutologin), + 4 => Some(GreeterError::InvalidUser), + value => Some(GreeterError::__Unknown(value)), + } + } +} + +impl StaticType for GreeterError { + fn static_type() -> Type { + unsafe { from_glib(light_dm_sys::lightdm_greeter_error_get_type()) } + } +} + +impl<'a> FromValueOptional<'a> for GreeterError { + unsafe fn from_value_optional(value: &Value) -> Option { + Some(FromValue::from_value(value)) + } +} + +impl<'a> FromValue<'a> for GreeterError { + unsafe fn from_value(value: &Value) -> Self { + from_glib(gobject_sys::g_value_get_enum(value.to_glib_none().0)) + } +} + +impl SetValue for GreeterError { + unsafe fn set_value(value: &mut Value, this: &Self) { + gobject_sys::g_value_set_enum(value.to_glib_none_mut().0, this.to_glib()) + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] +#[non_exhaustive] +pub enum MessageType { + Info, + Error, + #[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for MessageType { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!( + f, + "MessageType::{}", + match *self { + MessageType::Info => "Info", + MessageType::Error => "Error", + _ => "Unknown", + } + ) + } +} + +#[doc(hidden)] +impl ToGlib for MessageType { + type GlibType = light_dm_sys::LightDMMessageType; + + fn to_glib(&self) -> light_dm_sys::LightDMMessageType { + match *self { + MessageType::Info => light_dm_sys::LIGHTDM_MESSAGE_TYPE_INFO, + MessageType::Error => light_dm_sys::LIGHTDM_MESSAGE_TYPE_ERROR, + MessageType::__Unknown(value) => value, + } + } +} + +#[doc(hidden)] +impl FromGlib for MessageType { + fn from_glib(value: light_dm_sys::LightDMMessageType) -> Self { + match value { + 0 => MessageType::Info, + 1 => MessageType::Error, + value => MessageType::__Unknown(value), + } + } +} + +impl StaticType for MessageType { + fn static_type() -> Type { + unsafe { from_glib(light_dm_sys::lightdm_message_type_get_type()) } + } +} + +impl<'a> FromValueOptional<'a> for MessageType { + unsafe fn from_value_optional(value: &Value) -> Option { + Some(FromValue::from_value(value)) + } +} + +impl<'a> FromValue<'a> for MessageType { + unsafe fn from_value(value: &Value) -> Self { + from_glib(gobject_sys::g_value_get_enum(value.to_glib_none().0)) + } +} + +impl SetValue for MessageType { + unsafe fn set_value(value: &mut Value, this: &Self) { + gobject_sys::g_value_set_enum(value.to_glib_none_mut().0, this.to_glib()) + } +} + +#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Copy)] +#[non_exhaustive] +pub enum PromptType { + Question, + Secret, + #[doc(hidden)] + __Unknown(i32), +} + +impl fmt::Display for PromptType { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!( + f, + "PromptType::{}", + match *self { + PromptType::Question => "Question", + PromptType::Secret => "Secret", + _ => "Unknown", + } + ) + } +} + +#[doc(hidden)] +impl ToGlib for PromptType { + type GlibType = light_dm_sys::LightDMPromptType; + + fn to_glib(&self) -> light_dm_sys::LightDMPromptType { + match *self { + PromptType::Question => light_dm_sys::LIGHTDM_PROMPT_TYPE_QUESTION, + PromptType::Secret => light_dm_sys::LIGHTDM_PROMPT_TYPE_SECRET, + PromptType::__Unknown(value) => value, + } + } +} + +#[doc(hidden)] +impl FromGlib for PromptType { + fn from_glib(value: light_dm_sys::LightDMPromptType) -> Self { + match value { + 0 => PromptType::Question, + 1 => PromptType::Secret, + value => PromptType::__Unknown(value), + } + } +} + +impl StaticType for PromptType { + fn static_type() -> Type { + unsafe { from_glib(light_dm_sys::lightdm_prompt_type_get_type()) } + } +} + +impl<'a> FromValueOptional<'a> for PromptType { + unsafe fn from_value_optional(value: &Value) -> Option { + Some(FromValue::from_value(value)) + } +} + +impl<'a> FromValue<'a> for PromptType { + unsafe fn from_value(value: &Value) -> Self { + from_glib(gobject_sys::g_value_get_enum(value.to_glib_none().0)) + } +} + +impl SetValue for PromptType { + unsafe fn set_value(value: &mut Value, this: &Self) { + gobject_sys::g_value_set_enum(value.to_glib_none_mut().0, this.to_glib()) + } +} diff --git a/src/auto/functions.rs b/src/auto/functions.rs new file mode 100644 index 0000000..a6a4017 --- /dev/null +++ b/src/auto/functions.rs @@ -0,0 +1,135 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use glib; +use glib::object::IsA; +use glib::translate::*; +use glib::GString; +use light_dm_sys; +use std::ptr; +use Language; +use Layout; +use Session; + +pub fn get_can_hibernate() -> bool { + unsafe { from_glib(light_dm_sys::lightdm_get_can_hibernate()) } +} + +pub fn get_can_restart() -> bool { + unsafe { from_glib(light_dm_sys::lightdm_get_can_restart()) } +} + +pub fn get_can_shutdown() -> bool { + unsafe { from_glib(light_dm_sys::lightdm_get_can_shutdown()) } +} + +pub fn get_can_suspend() -> bool { + unsafe { from_glib(light_dm_sys::lightdm_get_can_suspend()) } +} + +pub fn get_hostname() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_get_hostname()) } +} + +pub fn get_language() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_get_language()) } +} + +pub fn get_languages() -> Vec { + unsafe { FromGlibPtrContainer::from_glib_none(light_dm_sys::lightdm_get_languages()) } +} + +pub fn get_layout() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_get_layout()) } +} + +pub fn get_layouts() -> Vec { + unsafe { FromGlibPtrContainer::from_glib_none(light_dm_sys::lightdm_get_layouts()) } +} + +pub fn get_motd() -> Option { + unsafe { from_glib_full(light_dm_sys::lightdm_get_motd()) } +} + +pub fn get_os_id() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_get_os_id()) } +} + +pub fn get_os_name() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_get_os_name()) } +} + +pub fn get_os_pretty_name() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_get_os_pretty_name()) } +} + +pub fn get_os_version() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_get_os_version()) } +} + +pub fn get_os_version_id() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_get_os_version_id()) } +} + +pub fn get_remote_sessions() -> Vec { + unsafe { FromGlibPtrContainer::from_glib_none(light_dm_sys::lightdm_get_remote_sessions()) } +} + +pub fn get_sessions() -> Vec { + unsafe { FromGlibPtrContainer::from_glib_none(light_dm_sys::lightdm_get_sessions()) } +} + +pub fn hibernate() -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_hibernate(&mut error); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } +} + +pub fn restart() -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_restart(&mut error); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } +} + +pub fn set_layout>(layout: &P) { + unsafe { + light_dm_sys::lightdm_set_layout(layout.as_ref().to_glib_none().0); + } +} + +pub fn shutdown() -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_shutdown(&mut error); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } +} + +pub fn suspend() -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_suspend(&mut error); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } +} diff --git a/src/auto/greeter.rs b/src/auto/greeter.rs new file mode 100644 index 0000000..87a757b --- /dev/null +++ b/src/auto/greeter.rs @@ -0,0 +1,1281 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use gio; +use gio_sys; +use glib; +use glib::object::Cast; +use glib::object::IsA; +use glib::signal::connect_raw; +use glib::signal::SignalHandlerId; +use glib::translate::*; +use glib::GString; +use glib_sys; +use gobject_sys; +use libc; +use light_dm_sys; +use std::boxed::Box as Box_; +use std::fmt; +use std::mem::transmute; +use std::pin::Pin; +use std::ptr; +use MessageType; +use PromptType; + +glib_wrapper! { + pub struct Greeter(Object); + + match fn { + get_type => || light_dm_sys::lightdm_greeter_get_type(), + } +} + +impl Greeter { + pub fn new() -> Greeter { + unsafe { from_glib_full(light_dm_sys::lightdm_greeter_new()) } + } +} + +impl Default for Greeter { + fn default() -> Self { + Self::new() + } +} + +pub const NONE_GREETER: Option<&Greeter> = None; + +pub trait GreeterExt: 'static { + fn authenticate(&self, username: Option<&str>) -> Result<(), glib::Error>; + + fn authenticate_as_guest(&self) -> Result<(), glib::Error>; + + fn authenticate_autologin(&self) -> Result<(), glib::Error>; + + fn authenticate_remote(&self, session: &str, username: Option<&str>) + -> Result<(), glib::Error>; + + fn cancel_authentication(&self) -> Result<(), glib::Error>; + + fn cancel_autologin(&self); + + fn connect_to_daemon< + P: IsA, + Q: FnOnce(Result<(), glib::Error>) + Send + 'static, + >( + &self, + cancellable: Option<&P>, + callback: Q, + ); + + fn connect_to_daemon_future( + &self, + ) -> Pin> + 'static>>; + + fn connect_to_daemon_sync(&self) -> Result<(), glib::Error>; + + fn ensure_shared_data_dir< + P: IsA, + Q: FnOnce(Result) + Send + 'static, + >( + &self, + username: &str, + cancellable: Option<&P>, + callback: Q, + ); + + fn ensure_shared_data_dir_future( + &self, + username: &str, + ) -> Pin> + 'static>>; + + fn ensure_shared_data_dir_sync(&self, username: &str) -> Result; + + fn get_authentication_user(&self) -> Option; + + fn get_autologin_guest_hint(&self) -> bool; + + fn get_autologin_session_hint(&self) -> Option; + + fn get_autologin_timeout_hint(&self) -> i32; + + fn get_autologin_user_hint(&self) -> Option; + + fn get_default_session_hint(&self) -> Option; + + fn get_has_guest_account_hint(&self) -> bool; + + fn get_hide_users_hint(&self) -> bool; + + fn get_hint(&self, name: &str) -> Option; + + fn get_in_authentication(&self) -> bool; + + fn get_is_authenticated(&self) -> bool; + + fn get_lock_hint(&self) -> bool; + + fn get_select_guest_hint(&self) -> bool; + + fn get_select_user_hint(&self) -> Option; + + fn get_show_manual_login_hint(&self) -> bool; + + fn get_show_remote_login_hint(&self) -> bool; + + fn respond(&self, response: &str) -> Result<(), glib::Error>; + + fn set_language(&self, language: &str) -> Result<(), glib::Error>; + + fn set_resettable(&self, resettable: bool); + + fn start_session< + P: IsA, + Q: FnOnce(Result<(), glib::Error>) + Send + 'static, + >( + &self, + session: Option<&str>, + cancellable: Option<&P>, + callback: Q, + ); + + fn start_session_future( + &self, + session: Option<&str>, + ) -> Pin> + 'static>>; + + fn start_session_sync(&self, session: Option<&str>) -> Result<(), glib::Error>; + + fn connect_authentication_complete(&self, f: F) -> SignalHandlerId; + + fn connect_autologin_timer_expired(&self, f: F) -> SignalHandlerId; + + fn connect_idle(&self, f: F) -> SignalHandlerId; + + fn connect_reset(&self, f: F) -> SignalHandlerId; + + fn connect_show_message( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_show_prompt( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_authentication_user_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_autologin_guest_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_autologin_session_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_autologin_timeout_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_autologin_user_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_default_session_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_has_guest_account_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_hide_users_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_in_authentication_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_is_authenticated_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_lock_hint_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_select_guest_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_select_user_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_show_manual_login_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_show_remote_login_hint_notify( + &self, + f: F, + ) -> SignalHandlerId; +} + +impl> GreeterExt for O { + fn authenticate(&self, username: Option<&str>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_authenticate( + self.as_ref().to_glib_none().0, + username.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn authenticate_as_guest(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_authenticate_as_guest( + self.as_ref().to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn authenticate_autologin(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_authenticate_autologin( + self.as_ref().to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn authenticate_remote( + &self, + session: &str, + username: Option<&str>, + ) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_authenticate_remote( + self.as_ref().to_glib_none().0, + session.to_glib_none().0, + username.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn cancel_authentication(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_cancel_authentication( + self.as_ref().to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn cancel_autologin(&self) { + unsafe { + light_dm_sys::lightdm_greeter_cancel_autologin(self.as_ref().to_glib_none().0); + } + } + + fn connect_to_daemon< + P: IsA, + Q: FnOnce(Result<(), glib::Error>) + Send + 'static, + >( + &self, + cancellable: Option<&P>, + callback: Q, + ) { + let user_data: Box_ = Box_::new(callback); + unsafe extern "C" fn connect_to_daemon_trampoline< + Q: FnOnce(Result<(), glib::Error>) + Send + 'static, + >( + _source_object: *mut gobject_sys::GObject, + res: *mut gio_sys::GAsyncResult, + user_data: glib_sys::gpointer, + ) { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_connect_to_daemon_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 _); + callback(result); + } + let callback = connect_to_daemon_trampoline::; + unsafe { + light_dm_sys::lightdm_greeter_connect_to_daemon( + self.as_ref().to_glib_none().0, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + Some(callback), + Box_::into_raw(user_data) as *mut _, + ); + } + } + + fn connect_to_daemon_future( + &self, + ) -> Pin> + 'static>> { + Box_::pin(gio::GioFuture::new(self, move |obj, send| { + let cancellable = gio::Cancellable::new(); + obj.connect_to_daemon(Some(&cancellable), move |res| { + send.resolve(res); + }); + + cancellable + })) + } + + fn connect_to_daemon_sync(&self) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_connect_to_daemon_sync( + self.as_ref().to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn ensure_shared_data_dir< + P: IsA, + Q: FnOnce(Result) + Send + 'static, + >( + &self, + username: &str, + cancellable: Option<&P>, + callback: Q, + ) { + let user_data: Box_ = Box_::new(callback); + unsafe extern "C" fn ensure_shared_data_dir_trampoline< + Q: FnOnce(Result) + Send + 'static, + >( + _source_object: *mut gobject_sys::GObject, + res: *mut gio_sys::GAsyncResult, + user_data: glib_sys::gpointer, + ) { + let mut error = ptr::null_mut(); + let ret = light_dm_sys::lightdm_greeter_ensure_shared_data_dir_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 _); + callback(result); + } + let callback = ensure_shared_data_dir_trampoline::; + unsafe { + light_dm_sys::lightdm_greeter_ensure_shared_data_dir( + self.as_ref().to_glib_none().0, + username.to_glib_none().0, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + Some(callback), + Box_::into_raw(user_data) as *mut _, + ); + } + } + + fn ensure_shared_data_dir_future( + &self, + username: &str, + ) -> Pin> + 'static>> { + let username = String::from(username); + Box_::pin(gio::GioFuture::new(self, move |obj, send| { + let cancellable = gio::Cancellable::new(); + obj.ensure_shared_data_dir(&username, Some(&cancellable), move |res| { + send.resolve(res); + }); + + cancellable + })) + } + + fn ensure_shared_data_dir_sync(&self, username: &str) -> Result { + unsafe { + let mut error = ptr::null_mut(); + let ret = light_dm_sys::lightdm_greeter_ensure_shared_data_dir_sync( + self.as_ref().to_glib_none().0, + username.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(from_glib_full(ret)) + } else { + Err(from_glib_full(error)) + } + } + } + + fn get_authentication_user(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_greeter_get_authentication_user( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_autologin_guest_hint(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_autologin_guest_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_autologin_session_hint(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_greeter_get_autologin_session_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_autologin_timeout_hint(&self) -> i32 { + unsafe { + light_dm_sys::lightdm_greeter_get_autologin_timeout_hint(self.as_ref().to_glib_none().0) + } + } + + fn get_autologin_user_hint(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_greeter_get_autologin_user_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_default_session_hint(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_greeter_get_default_session_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_has_guest_account_hint(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_has_guest_account_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_hide_users_hint(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_hide_users_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_hint(&self, name: &str) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_greeter_get_hint( + self.as_ref().to_glib_none().0, + name.to_glib_none().0, + )) + } + } + + fn get_in_authentication(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_in_authentication( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_is_authenticated(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_is_authenticated( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_lock_hint(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_lock_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_select_guest_hint(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_select_guest_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_select_user_hint(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_greeter_get_select_user_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_show_manual_login_hint(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_show_manual_login_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_show_remote_login_hint(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_greeter_get_show_remote_login_hint( + self.as_ref().to_glib_none().0, + )) + } + } + + fn respond(&self, response: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_respond( + self.as_ref().to_glib_none().0, + response.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn set_language(&self, language: &str) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_set_language( + self.as_ref().to_glib_none().0, + language.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn set_resettable(&self, resettable: bool) { + unsafe { + light_dm_sys::lightdm_greeter_set_resettable( + self.as_ref().to_glib_none().0, + resettable.to_glib(), + ); + } + } + + fn start_session< + P: IsA, + Q: FnOnce(Result<(), glib::Error>) + Send + 'static, + >( + &self, + session: Option<&str>, + cancellable: Option<&P>, + callback: Q, + ) { + let user_data: Box_ = Box_::new(callback); + unsafe extern "C" fn start_session_trampoline< + Q: FnOnce(Result<(), glib::Error>) + Send + 'static, + >( + _source_object: *mut gobject_sys::GObject, + res: *mut gio_sys::GAsyncResult, + user_data: glib_sys::gpointer, + ) { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_start_session_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 _); + callback(result); + } + let callback = start_session_trampoline::; + unsafe { + light_dm_sys::lightdm_greeter_start_session( + self.as_ref().to_glib_none().0, + session.to_glib_none().0, + cancellable.map(|p| p.as_ref()).to_glib_none().0, + Some(callback), + Box_::into_raw(user_data) as *mut _, + ); + } + } + + fn start_session_future( + &self, + session: Option<&str>, + ) -> Pin> + 'static>> { + let session = session.map(ToOwned::to_owned); + Box_::pin(gio::GioFuture::new(self, move |obj, send| { + let cancellable = gio::Cancellable::new(); + obj.start_session( + session.as_ref().map(::std::borrow::Borrow::borrow), + Some(&cancellable), + move |res| { + send.resolve(res); + }, + ); + + cancellable + })) + } + + fn start_session_sync(&self, session: Option<&str>) -> Result<(), glib::Error> { + unsafe { + let mut error = ptr::null_mut(); + let _ = light_dm_sys::lightdm_greeter_start_session_sync( + self.as_ref().to_glib_none().0, + session.to_glib_none().0, + &mut error, + ); + if error.is_null() { + Ok(()) + } else { + Err(from_glib_full(error)) + } + } + } + + fn connect_authentication_complete(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn authentication_complete_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"authentication-complete\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + authentication_complete_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_autologin_timer_expired(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn autologin_timer_expired_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"autologin-timer-expired\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + autologin_timer_expired_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_idle(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn idle_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"idle\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + idle_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_reset(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn reset_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"reset\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + reset_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_show_message( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn show_message_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + text: *mut libc::c_char, + type_: light_dm_sys::LightDMMessageType, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f( + &Greeter::from_glib_borrow(this).unsafe_cast_ref(), + &GString::from_glib_borrow(text), + from_glib(type_), + ) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"show-message\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + show_message_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_show_prompt( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn show_prompt_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + text: *mut libc::c_char, + type_: light_dm_sys::LightDMPromptType, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f( + &Greeter::from_glib_borrow(this).unsafe_cast_ref(), + &GString::from_glib_borrow(text), + from_glib(type_), + ) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"show-prompt\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + show_prompt_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_authentication_user_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_authentication_user_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::authentication-user\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_authentication_user_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_autologin_guest_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_autologin_guest_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::autologin-guest-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_autologin_guest_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_autologin_session_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_autologin_session_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::autologin-session-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_autologin_session_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_autologin_timeout_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_autologin_timeout_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::autologin-timeout-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_autologin_timeout_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_autologin_user_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_autologin_user_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::autologin-user-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_autologin_user_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_default_session_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_default_session_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::default-session-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_default_session_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_has_guest_account_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_has_guest_account_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::has-guest-account-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_has_guest_account_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_hide_users_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_hide_users_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::hide-users-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_hide_users_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_in_authentication_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_in_authentication_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::in-authentication\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_in_authentication_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_is_authenticated_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_is_authenticated_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::is-authenticated\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_is_authenticated_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_lock_hint_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_lock_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::lock-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_lock_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_select_guest_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_select_guest_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::select-guest-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_select_guest_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_select_user_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_select_user_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::select-user-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_select_user_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_show_manual_login_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_show_manual_login_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::show-manual-login-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_show_manual_login_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_show_remote_login_hint_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_show_remote_login_hint_trampoline( + this: *mut light_dm_sys::LightDMGreeter, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Greeter::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::show-remote-login-hint\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_show_remote_login_hint_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } +} + +impl fmt::Display for Greeter { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "Greeter") + } +} diff --git a/src/auto/language.rs b/src/auto/language.rs new file mode 100644 index 0000000..75c87bf --- /dev/null +++ b/src/auto/language.rs @@ -0,0 +1,157 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use glib::object::Cast; +use glib::object::IsA; +use glib::signal::connect_raw; +use glib::signal::SignalHandlerId; +use glib::translate::*; +use glib::GString; +use glib::StaticType; +use glib::ToValue; +use glib_sys; +use light_dm_sys; +use std::boxed::Box as Box_; +use std::fmt; +use std::mem::transmute; + +glib_wrapper! { + pub struct Language(Object); + + match fn { + get_type => || light_dm_sys::lightdm_language_get_type(), + } +} + +#[derive(Clone, Default)] +pub struct LanguageBuilder { + code: Option, +} + +impl LanguageBuilder { + pub fn new() -> Self { + Self::default() + } + + pub fn build(self) -> Language { + let mut properties: Vec<(&str, &dyn ToValue)> = vec![]; + if let Some(ref code) = self.code { + properties.push(("code", code)); + } + glib::Object::new(Language::static_type(), &properties) + .expect("object new") + .downcast() + .expect("downcast") + } + + pub fn code(mut self, code: &str) -> Self { + self.code = Some(code.to_string()); + self + } +} + +pub const NONE_LANGUAGE: Option<&Language> = None; + +pub trait LanguageExt: 'static { + fn get_code(&self) -> Option; + + fn get_name(&self) -> Option; + + fn get_territory(&self) -> Option; + + fn matches(&self, code: &str) -> bool; + + fn connect_property_name_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_territory_notify(&self, f: F) -> SignalHandlerId; +} + +impl> LanguageExt for O { + fn get_code(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_language_get_code( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_name(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_language_get_name( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_territory(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_language_get_territory( + self.as_ref().to_glib_none().0, + )) + } + } + + fn matches(&self, code: &str) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_language_matches( + self.as_ref().to_glib_none().0, + code.to_glib_none().0, + )) + } + } + + fn connect_property_name_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_name_trampoline( + this: *mut light_dm_sys::LightDMLanguage, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Language::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::name\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_name_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_territory_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_territory_trampoline( + this: *mut light_dm_sys::LightDMLanguage, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&Language::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::territory\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_territory_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } +} + +impl fmt::Display for Language { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "Language") + } +} diff --git a/src/auto/layout.rs b/src/auto/layout.rs new file mode 100644 index 0000000..2c1908e --- /dev/null +++ b/src/auto/layout.rs @@ -0,0 +1,107 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use glib::object::Cast; +use glib::object::IsA; +use glib::translate::*; +use glib::GString; +use glib::StaticType; +use glib::ToValue; +use light_dm_sys; +use std::fmt; + +glib_wrapper! { + pub struct Layout(Object); + + match fn { + get_type => || light_dm_sys::lightdm_layout_get_type(), + } +} + +#[derive(Clone, Default)] +pub struct LayoutBuilder { + description: Option, + name: Option, + short_description: Option, +} + +impl LayoutBuilder { + pub fn new() -> Self { + Self::default() + } + + pub fn build(self) -> Layout { + let mut properties: Vec<(&str, &dyn ToValue)> = vec![]; + if let Some(ref description) = self.description { + properties.push(("description", description)); + } + if let Some(ref name) = self.name { + properties.push(("name", name)); + } + if let Some(ref short_description) = self.short_description { + properties.push(("short-description", short_description)); + } + glib::Object::new(Layout::static_type(), &properties) + .expect("object new") + .downcast() + .expect("downcast") + } + + pub fn description(mut self, description: &str) -> Self { + self.description = Some(description.to_string()); + self + } + + pub fn name(mut self, name: &str) -> Self { + self.name = Some(name.to_string()); + self + } + + pub fn short_description(mut self, short_description: &str) -> Self { + self.short_description = Some(short_description.to_string()); + self + } +} + +pub const NONE_LAYOUT: Option<&Layout> = None; + +pub trait LayoutExt: 'static { + fn get_description(&self) -> Option; + + fn get_name(&self) -> Option; + + fn get_short_description(&self) -> Option; +} + +impl> LayoutExt for O { + fn get_description(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_layout_get_description( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_name(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_layout_get_name( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_short_description(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_layout_get_short_description( + self.as_ref().to_glib_none().0, + )) + } + } +} + +impl fmt::Display for Layout { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "Layout") + } +} diff --git a/src/auto/mod.rs b/src/auto/mod.rs new file mode 100644 index 0000000..3a866c2 --- /dev/null +++ b/src/auto/mod.rs @@ -0,0 +1,58 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +mod greeter; +pub use self::greeter::GreeterExt; +pub use self::greeter::{Greeter, GreeterClass, NONE_GREETER}; + +mod language; +pub use self::language::LanguageBuilder; +pub use self::language::LanguageExt; +pub use self::language::{Language, LanguageClass, NONE_LANGUAGE}; + +mod layout; +pub use self::layout::LayoutBuilder; +pub use self::layout::LayoutExt; +pub use self::layout::{Layout, LayoutClass, NONE_LAYOUT}; + +mod session; +pub use self::session::SessionExt; +pub use self::session::{Session, SessionClass, NONE_SESSION}; + +mod user; +pub use self::user::UserExt; +pub use self::user::{User, UserClass, NONE_USER}; + +mod user_list; +pub use self::user_list::UserListExt; +pub use self::user_list::{UserList, UserListClass, NONE_USER_LIST}; + +mod enums; +pub use self::enums::GreeterError; +pub use self::enums::MessageType; +pub use self::enums::PromptType; + +pub mod functions; + +mod constants; +pub use self::constants::GREETER_SIGNAL_AUTHENTICATION_COMPLETE; +pub use self::constants::GREETER_SIGNAL_AUTOLOGIN_TIMER_EXPIRED; +pub use self::constants::GREETER_SIGNAL_IDLE; +pub use self::constants::GREETER_SIGNAL_RESET; +pub use self::constants::GREETER_SIGNAL_SHOW_MESSAGE; +pub use self::constants::GREETER_SIGNAL_SHOW_PROMPT; +pub use self::constants::SIGNAL_USER_CHANGED; +pub use self::constants::USER_LIST_SIGNAL_USER_ADDED; +pub use self::constants::USER_LIST_SIGNAL_USER_CHANGED; +pub use self::constants::USER_LIST_SIGNAL_USER_REMOVED; + +#[doc(hidden)] +pub mod traits { + pub use super::GreeterExt; + pub use super::LanguageExt; + pub use super::LayoutExt; + pub use super::SessionExt; + pub use super::UserExt; + pub use super::UserListExt; +} diff --git a/src/auto/session.rs b/src/auto/session.rs new file mode 100644 index 0000000..2c0a3ea --- /dev/null +++ b/src/auto/session.rs @@ -0,0 +1,153 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use glib::object::Cast; +use glib::object::IsA; +use glib::signal::connect_raw; +use glib::signal::SignalHandlerId; +use glib::translate::*; +use glib::GString; +use glib_sys; +use light_dm_sys; +use std::boxed::Box as Box_; +use std::fmt; +use std::mem::transmute; + +glib_wrapper! { + pub struct Session(Object); + + match fn { + get_type => || light_dm_sys::lightdm_session_get_type(), + } +} + +pub const NONE_SESSION: Option<&Session> = None; + +pub trait SessionExt: 'static { + fn get_comment(&self) -> Option; + + fn get_key(&self) -> Option; + + fn get_name(&self) -> Option; + + fn get_session_type(&self) -> Option; + + fn connect_property_comment_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_key_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_name_notify(&self, f: F) -> SignalHandlerId; +} + +impl> SessionExt for O { + fn get_comment(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_session_get_comment( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_key(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_session_get_key( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_name(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_session_get_name( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_session_type(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_session_get_session_type( + self.as_ref().to_glib_none().0, + )) + } + } + + fn connect_property_comment_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_comment_trampoline( + this: *mut light_dm_sys::LightDMSession, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + 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 _, + b"notify::comment\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_comment_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_key_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_key_trampoline( + this: *mut light_dm_sys::LightDMSession, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + 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 _, + b"notify::key\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_key_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_name_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_name_trampoline( + this: *mut light_dm_sys::LightDMSession, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + 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 _, + b"notify::name\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_name_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } +} + +impl fmt::Display for Session { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "Session") + } +} diff --git a/src/auto/user.rs b/src/auto/user.rs new file mode 100644 index 0000000..e00cc36 --- /dev/null +++ b/src/auto/user.rs @@ -0,0 +1,574 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use glib::object::Cast; +use glib::object::IsA; +use glib::signal::connect_raw; +use glib::signal::SignalHandlerId; +use glib::translate::*; +use glib::GString; +use glib_sys; +use light_dm_sys; +use std::boxed::Box as Box_; +use std::fmt; +use std::mem::transmute; + +glib_wrapper! { + pub struct User(Object); + + match fn { + get_type => || light_dm_sys::lightdm_user_get_type(), + } +} + +pub const NONE_USER: Option<&User> = None; + +pub trait UserExt: 'static { + fn get_background(&self) -> Option; + + fn get_display_name(&self) -> Option; + + fn get_has_messages(&self) -> bool; + + fn get_home_directory(&self) -> Option; + + fn get_image(&self) -> Option; + + fn get_is_locked(&self) -> bool; + + fn get_language(&self) -> Option; + + fn get_layout(&self) -> Option; + + fn get_layouts(&self) -> Vec; + + fn get_logged_in(&self) -> bool; + + fn get_name(&self) -> Option; + + fn get_real_name(&self) -> Option; + + fn get_session(&self) -> Option; + + fn get_uid(&self) -> u32; + + fn connect_changed(&self, f: F) -> SignalHandlerId; + + fn connect_property_background_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_display_name_notify(&self, f: F) + -> SignalHandlerId; + + fn connect_property_has_messages_notify(&self, f: F) + -> SignalHandlerId; + + fn connect_property_home_directory_notify( + &self, + f: F, + ) -> SignalHandlerId; + + fn connect_property_image_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_is_locked_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_language_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_layout_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_layouts_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_logged_in_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_name_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_real_name_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_session_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_uid_notify(&self, f: F) -> SignalHandlerId; +} + +impl> UserExt for O { + fn get_background(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_background( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_display_name(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_display_name( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_has_messages(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_user_get_has_messages( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_home_directory(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_home_directory( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_image(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_image( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_is_locked(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_user_get_is_locked( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_language(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_language( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_layout(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_layout( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_layouts(&self) -> Vec { + unsafe { + FromGlibPtrContainer::from_glib_none(light_dm_sys::lightdm_user_get_layouts( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_logged_in(&self) -> bool { + unsafe { + from_glib(light_dm_sys::lightdm_user_get_logged_in( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_name(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_name( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_real_name(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_real_name( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_session(&self) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_get_session( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_uid(&self) -> u32 { + unsafe { light_dm_sys::lightdm_user_get_uid(self.as_ref().to_glib_none().0) } + } + + fn connect_changed(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn changed_trampoline( + this: *mut light_dm_sys::LightDMUser, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"changed\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + changed_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_background_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_background_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::background\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_background_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_display_name_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_display_name_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::display-name\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_display_name_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_has_messages_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_has_messages_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::has-messages\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_has_messages_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_home_directory_notify( + &self, + f: F, + ) -> SignalHandlerId { + unsafe extern "C" fn notify_home_directory_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::home-directory\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_home_directory_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_image_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_image_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::image\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_image_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_is_locked_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_is_locked_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::is-locked\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_is_locked_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_language_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_language_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::language\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_language_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_layout_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_layout_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::layout\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_layout_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_layouts_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_layouts_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::layouts\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_layouts_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_logged_in_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_logged_in_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::logged-in\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_logged_in_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_name_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_name_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::name\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_name_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_real_name_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_real_name_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::real-name\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_real_name_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_session_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_session_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::session\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_session_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_uid_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_uid_trampoline( + this: *mut light_dm_sys::LightDMUser, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&User::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::uid\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_uid_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } +} + +impl fmt::Display for User { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "User") + } +} diff --git a/src/auto/user_list.rs b/src/auto/user_list.rs new file mode 100644 index 0000000..02a8529 --- /dev/null +++ b/src/auto/user_list.rs @@ -0,0 +1,227 @@ +// This file was generated by gir (https://github.com/gtk-rs/gir) +// from gir-files (https://github.com/gtk-rs/gir-files) +// DO NOT EDIT + +use glib::object::Cast; +use glib::object::IsA; +use glib::signal::connect_raw; +use glib::signal::SignalHandlerId; +use glib::translate::*; +use glib::StaticType; +use glib::Value; +use glib_sys; +use gobject_sys; +use light_dm_sys; +use std::boxed::Box as Box_; +use std::fmt; +use std::mem::transmute; +use User; + +glib_wrapper! { + pub struct UserList(Object); + + match fn { + get_type => || light_dm_sys::lightdm_user_list_get_type(), + } +} + +impl UserList { + pub fn get_instance() -> Option { + unsafe { from_glib_none(light_dm_sys::lightdm_user_list_get_instance()) } + } +} + +pub const NONE_USER_LIST: Option<&UserList> = None; + +pub trait UserListExt: 'static { + fn get_length(&self) -> i32; + + fn get_user_by_name(&self, username: &str) -> Option; + + fn get_users(&self) -> Vec; + + fn get_property_num_users(&self) -> i32; + + fn connect_user_added(&self, f: F) -> SignalHandlerId; + + fn connect_user_changed(&self, f: F) -> SignalHandlerId; + + fn connect_user_removed(&self, f: F) -> SignalHandlerId; + + fn connect_property_length_notify(&self, f: F) -> SignalHandlerId; + + fn connect_property_num_users_notify(&self, f: F) -> SignalHandlerId; +} + +impl> UserListExt for O { + fn get_length(&self) -> i32 { + unsafe { light_dm_sys::lightdm_user_list_get_length(self.as_ref().to_glib_none().0) } + } + + fn get_user_by_name(&self, username: &str) -> Option { + unsafe { + from_glib_none(light_dm_sys::lightdm_user_list_get_user_by_name( + self.as_ref().to_glib_none().0, + username.to_glib_none().0, + )) + } + } + + fn get_users(&self) -> Vec { + unsafe { + FromGlibPtrContainer::from_glib_none(light_dm_sys::lightdm_user_list_get_users( + self.as_ref().to_glib_none().0, + )) + } + } + + fn get_property_num_users(&self) -> i32 { + unsafe { + let mut value = Value::from_type(::static_type()); + gobject_sys::g_object_get_property( + self.to_glib_none().0 as *mut gobject_sys::GObject, + b"num-users\0".as_ptr() as *const _, + value.to_glib_none_mut().0, + ); + value + .get() + .expect("Return Value for property `num-users` getter") + .unwrap() + } + } + + fn connect_user_added(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn user_added_trampoline( + this: *mut light_dm_sys::LightDMUserList, + user: *mut light_dm_sys::LightDMUser, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f( + &UserList::from_glib_borrow(this).unsafe_cast_ref(), + &from_glib_borrow(user), + ) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"user-added\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + user_added_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_user_changed(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn user_changed_trampoline( + this: *mut light_dm_sys::LightDMUserList, + user: *mut light_dm_sys::LightDMUser, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f( + &UserList::from_glib_borrow(this).unsafe_cast_ref(), + &from_glib_borrow(user), + ) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"user-changed\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + user_changed_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_user_removed(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn user_removed_trampoline( + this: *mut light_dm_sys::LightDMUserList, + user: *mut light_dm_sys::LightDMUser, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f( + &UserList::from_glib_borrow(this).unsafe_cast_ref(), + &from_glib_borrow(user), + ) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"user-removed\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + user_removed_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_length_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_length_trampoline( + this: *mut light_dm_sys::LightDMUserList, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&UserList::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::length\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_length_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } + + fn connect_property_num_users_notify(&self, f: F) -> SignalHandlerId { + unsafe extern "C" fn notify_num_users_trampoline( + this: *mut light_dm_sys::LightDMUserList, + _param_spec: glib_sys::gpointer, + f: glib_sys::gpointer, + ) where + P: IsA, + { + let f: &F = &*(f as *const F); + f(&UserList::from_glib_borrow(this).unsafe_cast_ref()) + } + unsafe { + let f: Box_ = Box_::new(f); + connect_raw( + self.as_ptr() as *mut _, + b"notify::num-users\0".as_ptr() as *const _, + Some(transmute::<_, unsafe extern "C" fn()>( + notify_num_users_trampoline:: as *const (), + )), + Box_::into_raw(f), + ) + } + } +} + +impl fmt::Display for UserList { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "UserList") + } +} diff --git a/src/auto/versions.txt b/src/auto/versions.txt new file mode 100644 index 0000000..245b8be --- /dev/null +++ b/src/auto/versions.txt @@ -0,0 +1,2 @@ +Generated by gir (https://github.com/gtk-rs/gir @ 2abca11) +from gir-files (https://github.com/gtk-rs/gir-files @ b89185a) diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..25b6bbb --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,13 @@ +#[macro_use] +extern crate glib; +extern crate gio; +extern crate gio_sys; +extern crate glib_sys; +extern crate gobject_sys; +extern crate light_dm_sys; + +extern crate libc; + +pub use auto::*; + +mod auto;