diff --git a/.travis.yml b/.travis.yml index 4dc4bd00..d851f961 100644 --- a/.travis.yml +++ b/.travis.yml @@ -19,4 +19,4 @@ script: - ./build.sh - if [ "$GTK" = "3.18" ]; then FEAT="gtk_3_18"; fi - echo $FEAT - - cargo build --features "$FEAT gtk/embed-lgpl-docs" + - cargo build --features "$FEAT gtk/embed-lgpl-docs" --jobs 1 diff --git a/gdk/vendor.md b/gdk/vendor.md index 46de22a1..3fa78ad0 100644 --- a/gdk/vendor.md +++ b/gdk/vendor.md @@ -21,17 +21,27 @@ if (!g_app_info_launch_default_for_uri ("http://www.gtk.org", context, &error)) g_object_unref (context); ``` + +# Implements + +[`AppLaunchContextExt`](trait.AppLaunchContextExt.html) + +Trait containing all `AppLaunchContext` methods. + +# Implementors + +[`AppLaunchContext`](struct.AppLaunchContext.html) Creates a new `AppLaunchContext`. # Deprecated since 3.0 -Use `Display::get_app_launch_context` instead +Use `DisplayExt::get_app_launch_context` instead # Returns a new `AppLaunchContext` - + 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 @@ -42,29 +52,29 @@ it is up to the window manager to pick one, typically it will be the current workspace. ## `desktop` the number of a workspace, or -1 - + Sets the display on which applications will be launched when -using this context. See also `AppLaunchContext::set_screen`. +using this context. See also `AppLaunchContextExt::set_screen`. # Deprecated since 3.0 -Use `Display::get_app_launch_context` instead +Use `DisplayExt::get_app_launch_context` instead ## `display` a `Display` - + Sets the icon for applications that are launched with this context. Window Managers can use this information when displaying startup notification. -See also `AppLaunchContext::set_icon_name`. +See also `AppLaunchContextExt::set_icon_name`. ## `icon` a `gio::Icon`, or `None` - + 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 `AppLaunchContext::set_icon`. +in desktop files. See also `AppLaunchContextExt::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 @@ -72,16 +82,16 @@ the file that is passed to launched application or from the `gio::AppInfo` for the launched application itself. ## `icon_name` an icon name, or `None` - + Sets the screen on which applications will be launched when -using this context. See also `AppLaunchContext::set_display`. +using this context. See also `AppLaunchContextExt::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. ## `screen` a `Screen` - + Sets the timestamp of `self`. The timestamp should ideally be taken from the event that triggered the launch. @@ -91,10 +101,55 @@ typing in another window. This is also known as 'focus stealing prevention'. ## `timestamp` 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. + +# Returns + +a newly-allocated string containing the string + corresponding to `self`. When you are done with the + return value, you should free it using `g_free`. + +Finds or creates an atom corresponding to a given string. +## `atom_name` +a string. +## `only_if_exists` +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. + +# Returns + +the atom corresponding to `atom_name`. + +Finds or creates an atom corresponding to a given string. + +Note that this function is identical to `Atom_::intern` except +that if a new `Atom` 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). +## `atom_name` +a static string + +# Returns + +the atom corresponding to `atom_name` 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. @@ -109,6 +164,12 @@ 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. @@ -149,6 +210,16 @@ crossing because of a device switch (i.e. is synthetic as the pointer didn’t leave the window. A `Cursor` represents a cursor. Its contents are private. + +# Implements + +[`CursorExt`](trait.CursorExt.html) + +Trait containing all `Cursor` methods. + +# Implementors + +[`Cursor`](struct.Cursor.html) Creates a new cursor from the set of builtin cursors for the default display. See `Cursor::new_for_display`. @@ -166,25 +237,6 @@ cursor to create a new `Cursor` Creates a new cursor from the set of builtin cursors. -Some useful ones are: -- ![](right_ptr.png) `CursorType::RightPtr` (right-facing arrow) -- ![](crosshair.png) `CursorType::Crosshair` (crosshair) -- ![](xterm.png) `CursorType::Xterm` (I-beam) -- ![](watch.png) `CursorType::Watch` (busy) -- ![](fleur.png) `CursorType::Fleur` (for moving objects) -- ![](hand1.png) `CursorType::Hand1` (a right-pointing hand) -- ![](hand2.png) `CursorType::Hand2` (a left-pointing hand) -- ![](left_side.png) `CursorType::LeftSide` (resize left side) -- ![](right_side.png) `CursorType::RightSide` (resize right side) -- ![](top_left_corner.png) `CursorType::TopLeftCorner` (resize northwest corner) -- ![](top_right_corner.png) `CursorType::TopRightCorner` (resize northeast corner) -- ![](bottom_left_corner.png) `CursorType::BottomLeftCorner` (resize southwest corner) -- ![](bottom_right_corner.png) `CursorType::BottomRightCorner` (resize southeast corner) -- ![](top_side.png) `CursorType::TopSide` (resize top side) -- ![](bottom_side.png) `CursorType::BottomSide` (resize bottom side) -- ![](sb_h_double_arrow.png) `CursorType::SbHDoubleArrow` (move vertical splitter) -- ![](sb_v_double_arrow.png) `CursorType::SbVDoubleArrow` (move horizontal splitter) -- `CursorType::BlankCursor` (Blank cursor). Since 2.16 ## `display` the `Display` for which the cursor will be created ## `cursor_type` @@ -196,6 +248,44 @@ a new `Cursor` 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" ## `display` the `Display` for which the cursor will be created ## `name` @@ -210,11 +300,11 @@ 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 `Display::supports_cursor_alpha` and -`Display::supports_cursor_color` can be used to determine +The functions `DisplayExt::supports_cursor_alpha` and +`DisplayExt::supports_cursor_color` can be used to determine whether RGBA cursors are supported; -`Display::get_default_cursor_size` and -`Display::get_maximal_cursor_size` give information about +`DisplayExt::get_default_cursor_size` and +`DisplayExt::get_maximal_cursor_size` give information about cursor sizes. If `x` or `y` are `-1`, the pixbuf must have @@ -241,11 +331,11 @@ 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 `Display::supports_cursor_alpha` and -`Display::supports_cursor_color` can be used to determine +The functions `DisplayExt::supports_cursor_alpha` and +`DisplayExt::supports_cursor_color` can be used to determine whether RGBA cursors are supported; -`Display::get_default_cursor_size` and -`Display::get_maximal_cursor_size` give information about +`DisplayExt::get_default_cursor_size` and +`DisplayExt::get_maximal_cursor_size` give information about cursor sizes. On the X backend, support for RGBA cursors requires a @@ -265,19 +355,19 @@ the vertical offset of the “hotspot” of the cursor # Returns a new `Cursor`. - + Returns the cursor type for this cursor. # Returns a `CursorType` - + Returns the display on which the `Cursor` is defined. # Returns the `Display` associated to `self` - + Returns a `gdk_pixbuf::Pixbuf` with the image used to display the cursor. Note that depending on the capabilities of the windowing system and @@ -288,7 +378,7 @@ case, `None` is returned. a `gdk_pixbuf::Pixbuf` representing `self`, or `None` - + Returns a cairo image surface with the image used to display the cursor. Note that depending on the capabilities of the windowing system and @@ -308,7 +398,7 @@ Location to store the hotspot y position, a `cairo::Surface` representing `self`, or `None` - + Adds a reference to `self`. # Deprecated since 3.0 @@ -318,7 +408,7 @@ Use `gobject::Object::ref` instead # Returns Same `self` that was passed in - + Removes a reference from `self`, deallocating the cursor if no references remain. @@ -326,7 +416,12 @@ if no references remain. Use `gobject::Object::unref` instead -The standard cursors available. +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 `Cursor::new_from_name`. ![](X_cursor.png) @@ -495,8 +590,18 @@ as a keyboard, a mouse, a touchpad, etc. See the `DeviceManager` documentation for more information about the various kinds of master and slave devices, and their relationships. + +# Implements + +[`DeviceExt`](trait.DeviceExt.html) + +Trait containing all `Device` methods. + +# Implementors + +[`Device`](struct.Device.html) -Frees an array of `TimeCoord` that was returned by `Device::get_history`. +Frees an array of `TimeCoord` that was returned by `DeviceExt::get_history`. ## `events` an array of `TimeCoord`. ## `n_events` @@ -524,7 +629,7 @@ location to store boolean indicating whether `true` if this application currently has the keyboard grabbed. - + Returns the associated device to `self`, if `self` is of type `DeviceType::Master`, it will return the paired pointer or keyboard. @@ -539,7 +644,12 @@ returned, as there is no associated device. The associated device, or `None` - + +Returns the axes currently available on the device. + +Feature: `v3_22` + + Interprets an array of double as axis values for a given device, and locates the value in the array for a given axis use. ## `axes` @@ -552,7 +662,7 @@ location to store the found value. # Returns `true` if the given axis use was found, otherwise `false` - + Returns the axis use for `index_`. ## `index_` the index of the axis. @@ -560,10 +670,10 @@ the index of the axis. # Returns a `AxisUse` specifying how the axis is used. - + 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 `Device::list_axes` +by `DeviceExt::list_axes` ## `axes` pointer to an array of axes ## `axis_label` @@ -574,27 +684,27 @@ location to store the found value. # Returns `true` if the given axis use was found, otherwise `false`. - + Returns the device type for `self`. # Returns the `DeviceType` for `self`. - + Returns the `Display` to which `self` pertains. # Returns a `Display`. This memory is owned by GTK+, and must not be freed or unreffed. - + Determines whether the pointer follows device motion. This is not meaningful for keyboard devices, which don't have a pointer. # Returns `true` if the pointer follows device motion - + 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 @@ -602,7 +712,7 @@ 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 `Window::set_event_compression` to get +Note that there is also `WindowExt::set_event_compression` to get more motion events delivered directly, independent of the windowing system. ## `window` @@ -623,7 +733,7 @@ location to store the length of `true` if the windowing system supports motion history and at least one event was found. - + If `index_` has a valid keyval, this function will return `true` and fill in `keyval` and `modifiers` with the keyval settings. ## `index_` @@ -636,7 +746,7 @@ return value for modifiers. # Returns `true` if keyval is set for `index`. - + 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`, @@ -649,35 +759,35 @@ Feature: `v3_12` # Returns the last window the device - + Determines the mode of the device. # Returns a `InputSource` - + Returns the number of axes the device currently has. # Returns the number of axes. - + Returns the number of keys the device currently has. # Returns the number of keys. - + Determines the name of the device. # Returns a name - + Gets the current location of `self`. As a slave device coordinates are those of its master pointer, This function may not be called on devices of type `DeviceType::Slave`, -unless there is an ongoing grab on them, see `Device::grab`. +unless there is an ongoing grab on them, see `DeviceExt::grab`. ## `screen` location to store the `Screen` the `self` is on, or `None`. @@ -685,11 +795,11 @@ location to store the `Screen` location to store root window X coordinate of `self`, or `None`. ## `y` location to store root window Y coordinate of `self`, or `None`. - + Gets the current location of `self` 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 `DeviceType::Slave`, -unless there is an ongoing grab on them. See `Device::grab`. +unless there is an ongoing grab on them. See `DeviceExt::grab`. Feature: `v3_10` @@ -700,10 +810,10 @@ location to store the `Screen` location to store root window X coordinate of `self`, or `None`. ## `y` location to store root window Y coordinate of `self`, or `None`. - + Returns the product ID of this device, or `None` if this information couldn't be obtained. This ID is retrieved from the device, and is thus constant for -it. See `Device::get_vendor_id` for more information. +it. See `DeviceExt::get_vendor_id` for more information. Feature: `v3_16` @@ -711,17 +821,27 @@ Feature: `v3_16` # Returns the product ID, or `None` - + +Returns the `Seat` the device belongs to. + +Feature: `v3_20` + + +# Returns + +A `Seat`. This memory is owned by GTK+ and + must not be freed. + Determines the type of the device. # Returns a `InputSource` - + 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 `DeviceType::Slave`, -unless there is an ongoing grab on them. See `Device::grab`. +unless there is an ongoing grab on them. See `DeviceExt::grab`. ## `window` a `Window`. ## `axes` @@ -729,12 +849,12 @@ an array of doubles to store the values of the axes of `self` in, or `None`. ## `mask` location to store the modifiers, or `None`. - + Returns the vendor ID of this device, or `None` if this information couldn't be obtained. This ID is retrieved from the device, and is thus constant for it. -This function, together with `Device::get_product_id`, can be used to eg. +This function, together with `DeviceExt::get_product_id`, can be used to eg. compose `gio::Settings` paths to store settings for this device. @@ -764,13 +884,13 @@ Feature: `v3_16` # Returns the vendor ID, or `None` - + Obtains the window underneath `self`, returning the location of the device in `win_x` and `win_y`. Returns `None` if the window tree under `self` 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 `DeviceType::Slave`, -unless there is an ongoing grab on them, see `Device::grab`. +unless there is an ongoing grab on them, see `DeviceExt::grab`. ## `win_x` return location for the X coordinate of the device location, relative to the window origin, or `None`. @@ -782,14 +902,14 @@ return location for the Y coordinate of the device location, the `Window` under the device position, or `None`. - + Obtains the window underneath `self`, returning the location of the device in `win_x` and `win_y` in double precision. Returns `None` if the window tree under `self` 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 `DeviceType::Slave`, -unless there is an ongoing grab on them, see `Device::grab`. +unless there is an ongoing grab on them, see `DeviceExt::grab`. ## `win_x` return location for the X coordinate of the device location, relative to the window origin, or `None`. @@ -801,9 +921,9 @@ return location for the Y coordinate of the device location, the `Window` under the device position, or `None`. - + Grabs the device so that all events coming from this device are passed to -this application until the device is ungrabbed with `Device::ungrab`, +this application until the device is ungrabbed with `DeviceExt::ungrab`, or the window becomes unviewable. This overrides any previous grab on the device by this client. @@ -823,6 +943,10 @@ It is equivalent to a pointer grab on the window with `owner_events` set to 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 `EventGrabBroken` events that are emitted when the grab ends unvoluntarily. + +# Deprecated since 3.20 + +Use `SeatExt::grab` instead. ## `window` the `Window` which will own the grab (the grab window) ## `grab_ownership` @@ -850,7 +974,7 @@ the timestamp of the event which led to this pointer grab. This # Returns `GrabStatus::Success` if the grab was successful. - + Returns a `glib::List` of ``GdkAtoms``, containing the labels for the axes that `self` currently has. @@ -858,7 +982,7 @@ the axes that `self` currently has. A `glib::List` of ``GdkAtoms``, free with `glib::List::free`. - + If the device if of type `DeviceType::Master`, it will return the list of slave devices attached to it, otherwise it will return `None` @@ -869,13 +993,13 @@ the list of slave devices attached to it, otherwise it will return the list of slave devices, or `None`. The list must be freed with `glib::List::free`, the contents of the list are owned by GTK+ and should not be freed. - + Specifies how an axis of a device is used. ## `index_` the index of the axis ## `use_` specifies how the axis is used - + Specifies the X key event to generate when a macro button of a device is pressed. ## `index_` @@ -884,7 +1008,7 @@ the index of the macro button to set the keyval to generate ## `modifiers` 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. @@ -898,11 +1022,15 @@ the input mode. # Returns `true` if the mode was successfully changed. - + Release any grab on `self`. + +# Deprecated since 3.20 + +Use `SeatExt::ungrab` instead. ## `time_` a timestap (e.g. `GDK_CURRENT_TIME`). - + Warps `self` 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 @@ -940,9 +1068,9 @@ 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, -`Window::set_support_multidevice` must be called on +`WindowExt::set_support_multidevice` must be called on ``GdkWindows`` (or `gtk_widget_set_support_multidevice` on widgets). -window. See the `Window::set_support_multidevice` documentation +window. See the `WindowExt::set_support_multidevice` documentation for more information. On X11, multi-device support is implemented through XInput 2. @@ -954,7 +1082,7 @@ 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 `DeviceManager::get_client_pointer`. +pointer can be accessed via `DeviceManagerExt::get_client_pointer`. Conceptually, in multidevice mode there are 2 device types. Virtual devices (or master devices) are represented by the pointer cursors @@ -964,7 +1092,7 @@ 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 -`Device::get_associated_device`. +`DeviceExt::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 @@ -1013,26 +1141,40 @@ 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 -`Device::grab` and `Device::set_mode`. +`DeviceExt::grab` and `DeviceExt::set_mode`. In order to listen for events coming from devices -other than a virtual device, `Window::set_device_events` must be +other than a virtual device, `WindowExt::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 `Device::get_axis`. In multidevice mode, virtual +queried through `DeviceExt::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 `Device:n-axes` property will be notified, and -`Device::list_axes` will return the new device axes. +`DeviceExt::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 `Device::set_key`. - +keyboard events. The mapping is set using `DeviceExt::set_key`. + +In GTK+ 3.20, a new `Seat` object has been introduced that +supersedes `DeviceManager` and should be preferred in newly +written code. + +# Implements + +[`DeviceManagerExt`](trait.DeviceManagerExt.html) + +Trait containing all `DeviceManager` methods. + +# Implementors + +[`DeviceManager`](struct.DeviceManager.html) + 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. @@ -1040,11 +1182,15 @@ 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 `Device` to operate on. +# Deprecated since 3.20 + +Use `SeatExt::get_pointer` instead. + # Returns The client pointer. This memory is owned by GDK and must not be freed or unreferenced. - + Gets the `Display` associated to `self`. # Returns @@ -1052,9 +1198,14 @@ Gets the `Display` associated to `self`. the `Display` to which `self` is associated to, or `None`. This memory is owned by GDK and must not be freed or unreferenced. - + Returns the list of devices of type `type_` currently attached to `self`. + +# Deprecated since 3.20 + +, use `SeatExt::get_pointer`, `SeatExt::get_keyboard` + and `SeatExt::get_slaves` instead. ## `type_` device type to get. @@ -1064,6 +1215,81 @@ 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. + + + +Feature: `v3_22` + +# Implements + +[`DeviceToolExt`](trait.DeviceToolExt.html) + +Trait containing all `DeviceTool` methods. + +Feature: `v3_22` + +# Implementors + +[`DeviceTool`](struct.DeviceTool.html) + +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 `DeviceToolExt::get_serial`). + +This is a more concrete (and device specific) method to identify +a `DeviceTool` than `DeviceToolExt::get_tool_type`, as a tablet +may support multiple devices with the same `DeviceToolType`, +but having different hardware identificators. + +Feature: `v3_22` + + +# Returns + +The hardware identificator of this tool. + +Gets the serial of this tool, this value can be used to identify a +physical tool (eg. a tablet pen) across program executions. + +Feature: `v3_22` + + +# Returns + +The serial ID for this tool + +Gets the `DeviceToolType` of the tool. + +Feature: `v3_22` + + +# Returns + +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. + +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. + +Feature: `v3_22` + Indicates the device type. See [above][`DeviceManager`.description] for more information about the meaning of these device types. @@ -1093,7 +1319,17 @@ access the keyboard(s) and mouse pointer(s) of the display. Most of the input device handling has been factored out into the separate `DeviceManager` object. Every display has a device manager, which you can obtain using -`Display::get_device_manager`. +`DisplayExt::get_device_manager`. + +# Implements + +[`DisplayExt`](trait.DisplayExt.html) + +Trait containing all `Display` methods. + +# Implementors + +[`Display`](struct.Display.html) Gets the default `Display`. This is a convenience function for: @@ -1128,12 +1364,12 @@ This symbol was never meant to be used outside the default display, if it could be opened, otherwise `None`. - + Emits a short beep on `self` - + Closes the connection to the windowing system for the given display, and cleans up associated resources. - + Returns `true` if there is an ongoing grab on `device` for `self`. ## `device` a `Device` @@ -1141,7 +1377,7 @@ a `Device` # Returns `true` if there is a grab in effect for `device`. - + 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 @@ -1151,7 +1387,7 @@ 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. - + Returns a `AppLaunchContext` suitable for launching applications on the given display. @@ -1159,36 +1395,49 @@ applications on the given display. a new `AppLaunchContext` for `self`. Free with `gobject::Object::unref` when done - + Returns the default size to use for cursors on `self`. # Returns the default cursor size. - + Returns the default group leader window for all toplevel windows on `self`. This window is implicitly created by GDK. -See `Window::set_group`. +See `WindowExt::set_group`. # Returns The default group leader window for `self` - + Get the default `Screen` for `self`. # Returns the default `Screen` object for `self` - + +Returns the default `Seat` for this display. + +Feature: `v3_20` + + +# Returns + +the default seat. + Returns the `DeviceManager` associated to `self`. +# Deprecated since 3.20 + +Use `DisplayExt::get_default_seat` and `Seat` operations. + # Returns A `DeviceManager`, or `None`. This memory is owned by GDK and must not be freed or unreferenced. - + Gets the next ``GdkEvent`` to be processed for `self`, fetching events from the windowing system if necessary. @@ -1197,13 +1446,64 @@ windowing system if necessary. the next ``GdkEvent`` to be processed, or `None` if no events are pending. The returned ``GdkEvent`` should be freed with `gdk_event_free`. - + Gets the maximal size to use for cursors on `self`. ## `width` the return location for the maximal cursor width ## `height` the return location for the maximal cursor height - + +Gets a monitor associated with this display. + +Feature: `v3_22` + +## `monitor_num` +number of the monitor + +# Returns + +the `Monitor`, or `None` if + `monitor_num` is not a valid monitor number + +Gets the monitor in which the point (`x`, `y`) is located, +or a nearby monitor if the point is not in any monitor. + +Feature: `v3_22` + +## `x` +the x coordinate of the point +## `y` +the y coordinate of the point + +# Returns + +the monitor containing 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. + +Feature: `v3_22` + +## `window` +a `Window` + +# Returns + +the monitor with the largest overlap with `window` + +Gets the number of monitors that belong to `self`. + +The returned number is valid until the next emission of the +`Display::monitor-added` or `Display::monitor-removed` signal. + +Feature: `v3_22` + + +# Returns + +the number of monitors + Gets the number of screen managed by the `self`. # Deprecated since 3.10 @@ -1213,20 +1513,20 @@ The number of screens is always 1. # Returns number of screens. - + Gets the name of the display. # Returns a string representing the display name. This string is owned by GDK and should not be modified or freed. - + Gets the current location of the pointer and the current modifier mask for a given display. # Deprecated since 3.0 -Use `Device::get_position` instead. +Use `DeviceExt::get_position` instead. ## `screen` location to store the screen that the cursor is on, or `None`. @@ -1236,15 +1536,34 @@ location to store root window X coordinate of pointer, or `None`. location to store root window Y coordinate of pointer, or `None`. ## `mask` location to store current modifier mask, or `None` - + +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. + +Feature: `v3_22` + + +# Returns + +the primary monitor, or `None` if no primary + monitor is configured by the user + Returns a screen object for one of the screens of the display. + +# Deprecated since 3.20 + +There is only one screen; use `DisplayExt::get_default_screen` to get it. ## `screen_num` the screen number # Returns the `Screen` object - + Obtains the window underneath the mouse pointer, returning the location of the pointer in that window in `win_x`, `win_y` for `screen`. Returns `None` if the window under the mouse pointer is not known to GDK (for example, @@ -1252,7 +1571,7 @@ belongs to another application). # Deprecated since 3.0 -Use `Device::get_window_at_position` instead. +Use `DeviceExt::get_window_at_position` instead. ## `win_x` return location for x coordinate of the pointer location relative to the window origin, or `None` @@ -1264,41 +1583,51 @@ return location for y coordinate of the pointer location relative the window under the mouse pointer, or `None` - + Returns whether the display has events that are waiting to be processed. # Returns `true` if there are events ready to be processed. - + Finds out if the display has been closed. # Returns `true` if the display is closed. - + Release any keyboard grab # Deprecated since 3.0 -Use `Device::ungrab`, together with `Device::grab` +Use `DeviceExt::ungrab`, together with `DeviceExt::grab` instead. ## `time_` a timestap (e.g `GDK_CURRENT_TIME`). - + Returns the list of available input devices attached to `self`. The list is statically allocated and should not be freed. # Deprecated since 3.0 -Use `DeviceManager::list_devices` instead. +Use `DeviceManagerExt::list_devices` instead. # Returns a list of `Device` - + +Returns the list of seats known to `self`. + +Feature: `v3_20` + + +# Returns + +the + list of seats known to the `Display` + Indicates to the GUI environment that the application has finished loading, using a given identifier. @@ -1309,7 +1638,7 @@ disable that feature. ## `startup_id` a startup-notification identifier, for which notification process should be completed - + Gets a copy of the first ``GdkEvent`` in the `self`’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 @@ -1320,31 +1649,31 @@ that have already been moved to the GDK event queue.) a copy of the first ``GdkEvent`` on the event queue, or `None` if no events are in the queue. The returned ``GdkEvent`` should be freed with `gdk_event_free`. - + Test if the pointer is grabbed. # Deprecated since 3.0 -Use `Display::device_is_grabbed` instead. +Use `DisplayExt::device_is_grabbed` instead. # Returns `true` if an active X pointer grab is in effect - + Release any pointer grab. # Deprecated since 3.0 -Use `Device::ungrab`, together with `Device::grab` +Use `DeviceExt::ungrab`, together with `DeviceExt::grab` instead. ## `time_` a timestap (e.g. `GDK_CURRENT_TIME`). - + Appends a copy of the given event onto the front of the event queue for `self`. ## `event` a ``GdkEvent``. - + Request `EventOwnerChange` events for ownership changes of the selection named by the given atom. ## `selection` @@ -1355,22 +1684,22 @@ the `Atom` naming the selection for which whether `EventOwnerChange` events will be sent. - + Sets the double click distance (two clicks within this distance count as a double click and result in a `EventType::2buttonPress` event). -See also `Display::set_double_click_time`. +See also `DisplayExt::set_double_click_time`. Applications should not set this, it is a global user-configured setting. ## `distance` distance in pixels - + Sets the double click time (two clicks within this time interval count as a double click and result in a `EventType::2buttonPress` event). Applications should not set this, it is a global user-configured setting. ## `msec` 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 @@ -1385,7 +1714,7 @@ an array of targets if all available targets should be saved. ## `n_targets` 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 @@ -1394,8 +1723,8 @@ running. # Returns `true` if the display supports clipboard persistance. - -Returns `true` if `Window::set_composited` can be used + +Returns `true` if `WindowExt::set_composited` can be used to redirect drawing on the window using compositing. Currently this only works on X11 with XComposite and @@ -1409,7 +1738,7 @@ Compositing is an outdated technology that # Returns `true` if windows may be composited. - + Returns `true` if cursors can use an 8bit alpha channel on `self`. Otherwise, cursors are restricted to bilevel alpha (i.e. a mask). @@ -1417,7 +1746,7 @@ alpha (i.e. a mask). # Returns whether cursors can have alpha channels. - + Returns `true` if multicolored cursors are supported on `self`. Otherwise, cursors have only a forground and a background color. @@ -1425,14 +1754,14 @@ and a background color. # Returns whether cursors can have multiple colors. - + Returns `true` if `gdk_window_input_shape_combine_mask` can be used to modify the input shape of windows on `self`. # Returns `true` if windows with modified input shape are supported - + Returns whether `EventOwnerChange` events will be sent when the owner of a selection changes. @@ -1440,24 +1769,24 @@ sent when the owner of a selection changes. whether `EventOwnerChange` events will be sent. - + Returns `true` if `gdk_window_shape_combine_mask` can be used to create shaped windows on `self`. # Returns `true` if shaped windows are supported - + 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 -`Display::sync` before `gdk_error_trap_pop` makes sure that any errors +`DisplayExt::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. - + Warps the pointer of `self` 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 @@ -1472,7 +1801,7 @@ for the color picker in the ``GtkColorSelectionDialog``. # Deprecated since 3.0 -Use `Device::warp` instead. +Use `DeviceExt::warp` instead. ## `screen` the screen of `self` to warp the pointer to ## `x` @@ -1520,6 +1849,16 @@ macros like GDK_IS_X11_DISPLAY() to find out which backend is in use: #endif g_error ("Unsupported GDK backend"); ``` + +# Implements + +[`DisplayManagerExt`](trait.DisplayManagerExt.html) + +Trait containing all `DisplayManager` methods. + +# Implementors + +[`DisplayManager`](struct.DisplayManager.html) Gets the singleton `DisplayManager` object. @@ -1534,14 +1873,14 @@ to limit what backends can be used. The global `DisplayManager` singleton; `gdk_parse_args`, `gdk_init`, or `gdk_init_check` must have been called first. - + Gets the default `Display`. # Returns a `Display`, or `None` if there is no default display. - + List all currently open displays. # Returns @@ -1549,7 +1888,7 @@ List all currently open displays. a newly allocated `glib::SList` of `Display` objects. Free with `glib::SList::free` when you are done with it. - + Opens a display. ## `name` the name of the display to open @@ -1558,66 +1897,140 @@ the name of the display to open a `Display`, or `None` if the display could not be opened - + Sets `display` as the default display. ## `display` a `Display` + +Used in `DragContext` to the reason of a cancelled DND operation. + +There is no suitable drop target. + +Drag cancelled by the user + +Unspecified error. + +Feature: `v3_20` + - + +# Implements + +[`DragContextExt`](trait.DragContextExt.html) + +Trait containing all `DragContext` methods. + +# Implementors + +[`DragContext`](struct.DragContext.html) + Determines the bitmask of actions proposed by the source if -`DragContext::get_suggested_action` returns `DragAction::Ask`. +`DragContextExt::get_suggested_action` returns `DragAction::Ask`. # Returns the `DragAction` flags - + Returns the destination windw for the DND operation. # Returns a `Window` - + Returns the `Device` associated to the drag context. # Returns The `Device` associated to `self`. - + +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 `self` and will be destroyed when +the drag operation is over. + +Feature: `v3_20` + + +# Returns + +the drag window, or `None` + Returns the drag protocol thats used by this context. # Returns the drag protocol - + Determines the action chosen by the drag destination. # Returns a `DragAction` value - + Returns the `Window` where the DND operation started. # Returns a `Window` - + Determines the suggested drag action of the context. # Returns a `DragAction` value - + Retrieves the list of targets of the context. # Returns a `glib::List` of targets - + +Requests the drag and drop operation to be managed by `self`. +When a drag and drop operation becomes managed, the `DragContext` +will internally handle all input and source-side `EventDND` events +as required by the windowing system. + +Once the drag and drop operation is managed, the drag context will +emit the following signals: +- The `DragContext::action-changed` signal whenever the final action + to be performed by the drag and drop operation changes. +- The `DragContext::drop-performed` signal after the user performs + the drag and drop gesture (typically by releasing the mouse button). +- The `DragContext::dnd-finished` signal after the drag and drop + operation concludes (after all ``GdkSelection`` transfers happen). +- The `DragContext::cancel` signal if the drag and drop operation is + finished but doesn't happen over an accepting destination, or is + cancelled through other means. + +Feature: `v3_20` + +## `ipc_window` +Window to use for IPC messaging/events +## `actions` +the actions supported by the drag source + +# Returns + +`true` if the drag and drop operation is managed. + Associates a `Device` to `self`, so all Drag and Drop events for `self` are emitted as if they came from this device. ## `device` a `Device` + +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. + +Feature: `v3_20` + +## `hot_x` +x coordinate of the drag window hotspot +## `hot_y` +y coordinate of the drag window hotspot Used in `DragContext` to indicate the protocol according to which DND is done. @@ -1638,6 +2051,74 @@ The complex OLE2 DND protocol (not implemented). Intra-application DND. Wayland DND protocol. + +`DrawingContext` is an object that represents the current drawing +state of a `Window`. + +It's possible to use a `DrawingContext` to draw on a `Window` +via rendering API like Cairo or OpenGL. + +A `DrawingContext` can only be created by calling `WindowExt::begin_draw_frame` +and will be valid until a call to `WindowExt::end_draw_frame`. + +`DrawingContext` is available since GDK 3.22 + +Feature: `v3_22` + +# Implements + +[`DrawingContextExt`](trait.DrawingContextExt.html) + +Trait containing all `DrawingContext` methods. + +Feature: `v3_22` + +# Implementors + +[`DrawingContext`](struct.DrawingContext.html) + +Retrieves a Cairo context to be used to draw on the `Window` +that created the `DrawingContext`. + +The returned context is guaranteed to be valid as long as the +`DrawingContext` is valid, that is between a call to +`WindowExt::begin_draw_frame` and `WindowExt::end_draw_frame`. + +Feature: `v3_22` + + +# Returns + +a Cairo context to be used to draw + the contents of the `Window`. The context is owned by the + `DrawingContext` and should not be destroyed + +Retrieves a copy of the clip region used when creating the `self`. + +Feature: `v3_22` + + +# Returns + +a Cairo region + +Retrieves the window that created the drawing `self`. + +Feature: `v3_22` + + +# Returns + +a `Window` + +Checks whether the given `DrawingContext` is valid. + +Feature: `v3_22` + + +# Returns + +`true` if the context is valid Used for button press and button release events. The `type` field will be one of `EventType::ButtonPress`, @@ -1852,6 +2333,27 @@ A touch event sequence has finished. This event type 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 `EventType` enumeration. Added in 2.18 @@ -1865,15 +2367,6 @@ Modern composited windowing systems with pervasive information. Generated when the state of a toplevel window changes. - -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 `FrameClock` tells the application when to update and repaint a window. This may be synced to the vertical refresh rate of the @@ -1889,44 +2382,56 @@ implementation or with mozRequestAnimationFrame in Firefox, for example. A frame clock is idle until someone requests a frame with -`FrameClock::request_phase`. At some later point that makes +`FrameClockExt::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 `FrameClock` class for documentation of the phases. `FrameClockPhase::Update` and the `FrameClock::update` signal are most interesting for application writers, and are used to update the animations, using the frame time -given by `FrameClock::get_frame_time`. +given by `FrameClockExt::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 `FrameClock::get_frame_time` that +is made so that all calls to `FrameClockExt::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 `FrameClock::get_frame_time` +time between an initial value from `FrameClockExt::get_frame_time` and the value inside the `FrameClock::update` signal of the clock, they will stay exactly synchronized. Feature: `v3_8` - + +# Implements + +[`FrameClockExt`](trait.FrameClockExt.html) + +Trait containing all `FrameClock` methods. + +Feature: `v3_8` + +# Implementors + +[`FrameClock`](struct.FrameClock.html) + Starts updates for an animation. Until a matching call to -`FrameClock::end_updating` is made, the frame clock will continually +`FrameClockExt::end_updating` is made, the frame clock will continually request a new frame with the `FrameClockPhase::Update` phase. This function may be called multiple times and frames will be -requested until `FrameClock::end_updating` is called the same +requested until `FrameClockExt::end_updating` is called the same number of times. Feature: `v3_8` - + Stops updates for an animation. See the documentation for -`FrameClock::begin_updating`. +`FrameClockExt::begin_updating`. Feature: `v3_8` - + Gets the frame timings for the current frame. Feature: `v3_8` @@ -1938,7 +2443,7 @@ the `FrameTimings` for the frame currently being processed, or even no frame is being processed, for the previous frame. Before any frames have been procesed, returns `None`. - + A `FrameClock` maintains a 64-bit counter that increments for each frame drawn. @@ -1950,7 +2455,7 @@ Feature: `v3_8` inside frame processing, the value of the frame counter for the current frame. Outside of frame processing, the frame counter for the last frame. - + 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 @@ -1965,13 +2470,13 @@ Feature: `v3_8` a timestamp in microseconds, in the timescale of of `g_get_monotonic_time`. - + `FrameClock` internally keeps a history of `FrameTimings` objects for recent frames that can be retrieved with -`FrameClock::get_timings`. The set of stored frames +`FrameClockExt::get_timings`. The set of stored frames is the set from the counter values given by -`FrameClock::get_history_start` and -`FrameClock::get_frame_counter`, inclusive. +`FrameClockExt::get_history_start` and +`FrameClockExt::get_frame_counter`, inclusive. Feature: `v3_8` @@ -1981,7 +2486,7 @@ Feature: `v3_8` the frame counter value for the oldest frame that is available in the internal frame history of the `FrameClock`. - + 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, @@ -2000,7 +2505,7 @@ a location to store the determined refresh 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 `FrameTimings` object holding timing information for the current frame or a recent frame. The `FrameTimings` object may not yet be complete: see `FrameTimings::get_complete`. @@ -2015,16 +2520,16 @@ the frame counter value identifying the frame to the `FrameTimings` object for the specified frame, or `None` if it is not available. See - `FrameClock::get_history_start`. - + `FrameClockExt::get_history_start`. + 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 -`FrameClock::request_phase` will be combined together +`FrameClockExt::request_phase` will be combined together and only one frame processed. If you are displaying animated content and want to continually request the `FrameClockPhase::Update` phase for a period of time, -you should use `FrameClock::begin_updating` instead, since +you should use `FrameClockExt::begin_updating` instead, since this allows GTK+ to adjust system parameters to get maximally smooth animations. @@ -2035,10 +2540,12 @@ the phase that is requested A `FrameTimings` object holds timing information for a single frame of the application’s displays. To retrieve `FrameTimings` objects, -use `FrameClock::get_timings` or `FrameClock::get_current_timings`. +use `FrameClockExt::get_timings` or `FrameClockExt::get_current_timings`. The information in `FrameTimings` 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. + +Feature: `v3_8` The timing information in a `FrameTimings` is filled in incrementally as the frame as drawn and passed off to the @@ -2070,7 +2577,7 @@ the frame counter value for this frame Returns the frame time for the frame. This is the time value that is typically used to time animations for the frame. See -`FrameClock::get_frame_time`. +`FrameClockExt::get_frame_time`. # Returns @@ -2082,7 +2589,7 @@ no predicted time may be available, if one is available, it will be available while the frame is being generated, in contrast to `FrameTimings::get_presentation_time`, which is only available after the frame has been presented. In general, if you are simply -animating, you should use `FrameClock::get_frame_time` rather +animating, you should use `FrameClockExt::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. @@ -2150,7 +2657,7 @@ Feature: `v3_8` OpenGL drawing context. ``GdkGLContexts`` are created for a `Window` using -`Window::create_gl_context`, and the context will match +`WindowExt::create_gl_context`, and the context will match the `Visual` of the window. A `GLContext` is not tied to any particular normal framebuffer. @@ -2172,11 +2679,11 @@ In order to create a new `GLContext` instance you need a `Window`, which you typically get during the realize call of a widget. -A `GLContext` is not realized until either `GLContext::make_current`, -or until it is realized using `GLContext::realize`. It is possible to +A `GLContext` is not realized until either `GLContextExt::make_current`, +or until it is realized using `GLContextExt::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 `Window::create_gl_context` by calling `GLContext::realize`. +calling `WindowExt::create_gl_context` by calling `GLContextExt::realize`. If the realization fails you have the option to change the settings of the `GLContext` and try again. @@ -2200,11 +2707,23 @@ You can check which `GLContext` is the current one by using that is currently set by calling `GLContext::clear_current`. Feature: `v3_16` + +# Implements + +[`GLContextExt`](trait.GLContextExt.html) + +Trait containing all `GLContext` methods. + +Feature: `v3_16` + +# Implementors + +[`GLContext`](struct.GLContext.html) Clears the current `GLContext`. Any OpenGL call after this function returns will be ignored -until `GLContext::make_current` is called. +until `GLContextExt::make_current` is called. Feature: `v3_16` @@ -2217,8 +2736,8 @@ Feature: `v3_16` # Returns the current `GLContext`, or `None` - -Retrieves the value set using `GLContext::set_debug_enabled`. + +Retrieves the value set using `GLContextExt::set_debug_enabled`. Feature: `v3_16` @@ -2226,7 +2745,7 @@ Feature: `v3_16` # Returns `true` if debugging is enabled - + Retrieves the `Display` the `self` is created for Feature: `v3_16` @@ -2235,8 +2754,8 @@ Feature: `v3_16` # Returns a `Display` or `None` - -Retrieves the value set using `GLContext::set_forward_compatible`. + +Retrieves the value set using `GLContextExt::set_forward_compatible`. Feature: `v3_16` @@ -2244,9 +2763,9 @@ Feature: `v3_16` # Returns `true` if the context should be forward compatible - + Retrieves the major and minor version requested by calling -`GLContext::set_required_version`. +`GLContextExt::set_required_version`. Feature: `v3_16` @@ -2254,7 +2773,7 @@ Feature: `v3_16` return location for the major version to request ## `minor` return location for the minor version to request - + Retrieves the `GLContext` that this `self` share data with. Feature: `v3_16` @@ -2263,7 +2782,16 @@ Feature: `v3_16` # Returns a `GLContext` or `None` - + +Checks whether the `self` is using an OpenGL or OpenGL ES profile. + +Feature: `v3_22` + + +# Returns + +`true` if the `GLContext` is using an OpenGL ES profile + Retrieves the OpenGL version of the `self`. The `self` must be realized prior to calling this function. @@ -2274,7 +2802,7 @@ Feature: `v3_16` return location for the major version ## `minor` return location for the minor version - + Retrieves the `Window` used by the `self`. Feature: `v3_16` @@ -2283,12 +2811,36 @@ Feature: `v3_16` # Returns a `Window` or `None` - + +Whether the `GLContext` is in legacy mode or not. + +The `GLContext` 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. + +Feature: `v3_20` + + +# Returns + +`true` if the GL context is in legacy mode + Makes the `self` the current one. Feature: `v3_16` - + Realizes the given `GLContext`. It is safe to call this function on a realized `GLContext`. @@ -2299,7 +2851,7 @@ Feature: `v3_16` # Returns `true` if the context is realized - + Sets whether the `GLContext` should perform extra validations and run time checking. This is useful during development, but has additional overhead. @@ -2311,7 +2863,7 @@ Feature: `v3_16` ## `enabled` whether to enable debugging in the context - + Sets whether the `GLContext` should be forward compatible. Forward compatibile contexts must not support OpenGL functionality that @@ -2326,7 +2878,7 @@ Feature: `v3_16` ## `compatible` 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. @@ -2340,6 +2892,25 @@ Feature: `v3_16` the major version to request ## `minor` 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 `self` 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 `self` +is realized. + +You should check the return value of `GLContextExt::get_use_es` after +calling `GLContextExt::realize` to decide whether to use the OpenGL or +OpenGL ES API, extensions, or shaders. + +Feature: `v3_22` + +## `use_es` +whether the context should use OpenGL ES instead of OpenGL, + or -1 to allow auto-detection Error enumeration for `GLContext`. @@ -2351,6 +2922,63 @@ The requested profile is not supported Feature: `v3_16` + +The `Geometry` 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 `Window` it creates. + +`WindowExt::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”: + + +```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. Defines how device grabs interact with other devices. @@ -2360,7 +2988,7 @@ Other devices’ events are blocked for the grab window. Other devices’ events are blocked for the whole application. -Returned by `Device::grab`, `gdk_pointer_grab` and `gdk_keyboard_grab` to +Returned by `DeviceExt::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. @@ -2375,7 +3003,7 @@ the grab window or the `confine_to` window are not the resource is frozen by an active grab of another client. -the grab failed for some other reason. +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 @@ -2435,6 +3063,13 @@ the device is a direct-input touch device, such 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. This enum is used with `Keymap::get_modifier_mask` in order to determine what modifiers the @@ -2463,6 +3098,149 @@ when any of these modifiers is pressed, the 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. + +`Monitor` objects represent the individual outputs that are +associated with a `Display`. `Display` has APIs to enumerate +monitors with `gdk_display_get_monitors` and to find particular +monitors with `DisplayExt::get_primary_monitor` or +`DisplayExt::get_monitor_at_window`. + +`Monitor` was introduced in GTK+ 3.22 and supersedes earlier +APIs in `Screen` to obtain monitor-related information. + +Feature: `v3_22` + +# Implements + +[`MonitorExt`](trait.MonitorExt.html) + +Trait containing all `Monitor` methods. + +Feature: `v3_22` + +# Implementors + +[`Monitor`](struct.Monitor.html) + +Gets the display that this monitor belongs to. + +Feature: `v3_22` + + +# Returns + +the display + +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 `MonitorExt::get_scale_factor`). + +Feature: `v3_22` + +## `geometry` +a `Rectangle` to be filled wiht the monitor geometry + +Gets the height in millimeters of the monitor. + +Feature: `v3_22` + + +# Returns + +the physical height of the monitor + +Gets the name of the monitor's manufacturer, if available. + +# Returns + +the name of the manufacturer, or `None` + +Gets the a string identifying the monitor model, if available. + +# Returns + +the monitor model, or `None` + +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. + +Feature: `v3_22` + + +# Returns + +the refresh rate in milli-Hertz, or 0 + +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 `WindowExt::get_scale_factor` instead. + +Feature: `v3_22` + + +# Returns + +the scale factor + +Gets information about the layout of red, green and blue +primaries for each pixel in this monitor, if available. + +Feature: `v3_22` + + +# Returns + +the subpixel layout + +Gets the width in millimeters of the monitor. + +Feature: `v3_22` + + +# Returns + +the physical width of the monitor + +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 +`MonitorExt::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. + +Feature: `v3_22` + +## `workarea` +a `Rectangle` to be filled with + the monitor workarea + +Gets whether this monitor should be considered primary +(see `DisplayExt::get_primary_monitor`). + +Feature: `v3_22` + + +# Returns + +`true` if `self` is primary Specifies the kind of crossing for `EventCrossing`. @@ -2495,33 +3273,146 @@ some other app claimed the ownership the window was destroyed the client was closed - -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 `EventProperty`. the property value was changed. the property was deleted. + +A `RGBA` is used to represent a (possibly translucent) +color, in a way that is compatible with cairos notion of color. + +Makes a copy of a `RGBA`. + +The result must be freed through `RGBA::free`. + +# Returns + +A newly allocated `RGBA`, with the same contents as `self` + +Compares two RGBA colors. +## `p2` +another `RGBA` pointer + +# Returns + +`true` if the two colors compare equal + +Frees a `RGBA` created with `RGBA::copy` + +A hash function suitable for using for a hash +table that stores ``GdkRGBAs``. + +# Returns + +The hash value for `self` + +Parses a textual representation of a color, filling in +the `red`, `green`, `blue` and `alpha` fields of the `self` `RGBA`. + +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 precentage values in the range 0% to 100%, and +a is a floating point value in the range 0 to 1. +## `spec` +the string specifying the color + +# Returns + +`true` if the parsing succeeded + +Returns a textual specification of `self` 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 floating point value in the range 0 to 1. + +These string forms are string forms those supported by +the CSS3 colors module, and can be parsed by `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. + +# Returns + +A newly allocated text string + +Defines the position and size of a rectangle. It is identical to +`cairo::RectangleInt`. + +Checks if the two given rectangles are equal. + +Feature: `v3_20` + +## `rect2` +a `Rectangle` + +# Returns + +`true` if the rectangles are equal. + +Calculates the intersection of two rectangles. It is allowed for +`dest` to be the same as either `self` 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 `None` for `dest`. +## `src2` +a `Rectangle` +## `dest` +return location for the +intersection of `self` and `src2`, or `None` + +# Returns + +`true` if the rectangles intersect. + +Calculates the union of two rectangles. +The union of rectangles `self` and `src2` is the smallest rectangle which +includes both `self` and `src2` within it. +It is allowed for `dest` to be the same as either `self` or `src2`. + +Note that this function does not ignore 'empty' rectangles (ie. with +zero width or height). +## `src2` +a `Rectangle` +## `dest` +return location for the union of `self` and `src2` `Screen` 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 `Screen` which -combines several physical monitors (see `Screen::get_n_monitors`). +combines several physical monitors (see `ScreenExt::get_n_monitors`). `Screen` 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 (`Screen::get_system_visual`), the dimensions -of the physical monitors (`Screen::get_monitor_geometry`), etc. +the default visual (`ScreenExt::get_system_visual`), the dimensions +of the physical monitors (`ScreenExt::get_monitor_geometry`), etc. + +# Implements + +[`ScreenExt`](trait.ScreenExt.html) + +Trait containing all `Screen` methods. + +# Implementors + +[`Screen`](struct.Screen.html) Gets the default screen for the default display. (See gdk_display_get_default ()). @@ -2531,7 +3422,13 @@ gdk_display_get_default ()). a `Screen`, or `None` if there is no default display. -Returns the height of the default screen in pixels. +Gets the height of the default screen in pixels. The returned +size is in ”application pixels”, not in ”device pixels” (see +`ScreenExt::get_monitor_scale_factor`). + +# Deprecated since 3.22 + +Use per-monitor information # Returns @@ -2540,12 +3437,22 @@ 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. +# Deprecated since 3.22 + +Use per-monitor information + # Returns the height of the default screen in millimeters, though it is not always correct. -Returns the width of the default screen in pixels. +Gets the width of the default screen in pixels. The returned +size is in ”application pixels”, not in ”device pixels” (see +`ScreenExt::get_monitor_scale_factor`). + +# Deprecated since 3.22 + +Use per-monitor information # Returns @@ -2554,11 +3461,15 @@ 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. +# Deprecated since 3.22 + +Use per-monitor information + # Returns 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 @@ -2574,38 +3485,58 @@ it is implementable on that platform. The returned window should be unrefed using `gobject::Object::unref` when no longer needed. +# Deprecated since 3.22 + + # Returns the currently active window, or `None`. - + Gets the display to which the `self` belongs. # Returns the display to which `self` belongs - -Gets any options previously set with `Screen::set_font_options`. + +Gets any options previously set with `ScreenExt::set_font_options`. # Returns the current font options, or `None` if no default font options have been set. - -Gets the height of `self` in pixels + +Gets the height of `self` in pixels. The returned size is in +”application pixels”, not in ”device pixels” (see +`ScreenExt::get_monitor_scale_factor`). + +# Deprecated since 3.22 + +Use per-monitor information instead # Returns the height of `self` in pixels. - + Returns the height of `self` in millimeters. -Note that on some X servers this value will not be correct. + +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. + +# Deprecated since 3.22 + +Use per-monitor information instead # Returns the heigth of `self` in millimeters. - + Returns the monitor number in which the point (`x`,`y`) is located. + +# Deprecated since 3.22 + +Use `DisplayExt::get_monitor_at_point` instead ## `x` the x coordinate in the virtual screen. ## `y` @@ -2615,9 +3546,13 @@ the y coordinate in the virtual screen. 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. - + Returns the number of the monitor in which the largest area of the bounding rectangle of `window` resides. + +# Deprecated since 3.22 + +Use `DisplayExt::get_monitor_at_window` instead ## `window` a `Window` @@ -2626,32 +3561,46 @@ a `Window` the monitor number in which most of `window` is located, or if `window` does not intersect any monitors, a monitor, close to `window`. - + Retrieves the `Rectangle` representing the size and position of -the individual monitor within the entire screen area. +the individual monitor within the entire screen area. The returned +geometry is in ”application pixels”, not in ”device pixels” (see +`ScreenExt::get_monitor_scale_factor`). Monitor numbers start at 0. To obtain the number of monitors of -`self`, use `Screen::get_n_monitors`. +`self`, use `ScreenExt::get_n_monitors`. Note that the size of the entire screen area can be retrieved via -`Screen::get_width` and `Screen::get_height`. +`ScreenExt::get_width` and `ScreenExt::get_height`. + +# Deprecated since 3.22 + +Use `MonitorExt::get_geometry` instead ## `monitor_num` the monitor number ## `dest` a `Rectangle` to be filled with the monitor geometry - + Gets the height in millimeters of the specified monitor. + +# Deprecated since 3.22 + +Use `MonitorExt::get_height_mm` instead ## `monitor_num` number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) # Returns the height of the monitor, or -1 if not available - + Returns the output name of the specified monitor. Usually something like VGA, DVI, or TV, not the actual product name of the display device. + +# Deprecated since 3.22 + +Use `MonitorExt::get_model` instead ## `monitor_num` number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) @@ -2659,34 +3608,44 @@ number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) a newly-allocated string containing the name of the monitor, or `None` if the name cannot be determined - -Returns the internal scale factor that maps from monitor coordiantes + +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 -particula monitor, but most of the time you’re drawing to a window -where it is better to use `Window::get_scale_factor` instead. +particular monitor, but most of the time you’re drawing to a window +where it is better to use `WindowExt::get_scale_factor` instead. Feature: `v3_10` + +# Deprecated since 3.22 + +Use `MonitorExt::get_scale_factor` instead ## `monitor_num` number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) # Returns the scale factor - + Gets the width in millimeters of the specified monitor, if available. + +# Deprecated since 3.22 + +Use `MonitorExt::get_width_mm` instead ## `monitor_num` number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) # Returns the width of the monitor, or -1 if not available - + Retrieves the `Rectangle` representing the size and position of -the “work area” on a monitor within the entire screen area. +the “work area” on a monitor within the entire screen area. The returned +geometry is in ”application pixels”, not in ”device pixels” (see +`ScreenExt::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 @@ -2697,26 +3656,37 @@ 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 -`self`, use `Screen::get_n_monitors`. +`self`, use `ScreenExt::get_n_monitors`. + +# Deprecated since 3.22 + +Use `MonitorExt::get_workarea` instead ## `monitor_num` the monitor number ## `dest` a `Rectangle` to be filled with the monitor workarea - + Returns the number of monitors which `self` consists of. +# Deprecated since 3.22 + +Use `DisplayExt::get_n_monitors` instead + # Returns number of monitors which `self` consists of - + Gets the index of `self` among the screens in the display -to which it belongs. (See `Screen::get_display`) +to which it belongs. (See `ScreenExt::get_display`) + +# Deprecated since 3.22 + # Returns the index - + Gets the primary monitor for `self`. The primary monitor is considered the monitor where the “main desktop” lives. While normal application windows typically allow the window @@ -2726,18 +3696,22 @@ 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. +# Deprecated since 3.22 + +Use `DisplayExt::get_primary_monitor` instead + # Returns An integer index for the primary monitor, or 0 if none is configured. - + Gets the resolution for font handling on the screen; see -`Screen::set_resolution` for full details. +`ScreenExt::set_resolution` for full details. # Returns the current resolution, or -1 if no resolution has been set. - + 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 `None` will @@ -2750,20 +3724,20 @@ 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 -`Window::set_opacity`. +`WindowExt::set_opacity`. # Returns a visual to use for windows with an alpha channel or `None` if the capability is not available. - + Gets the root window of `self`. # Returns the root window - + Retrieves a desktop-wide setting such as double-click time for the `Screen` `self`. @@ -2778,7 +3752,7 @@ location to store the value of the setting `true` if the setting existed and a value was stored in `value`, `false` otherwise. - + Get the system’s default visual for `self`. This is the visual for the root window of the display. The return value should not be freed. @@ -2786,7 +3760,7 @@ The return value should not be freed. # Returns the system visual - + Obtains a list of all toplevel windows known to GDK on the screen `self`. A toplevel window is a child of the root window (see `gdk_get_default_root_window`). @@ -2798,20 +3772,33 @@ its elements need not be freed. list of toplevel windows, free with `glib::List::free` - -Gets the width of `self` in pixels + +Gets the width of `self` in pixels. The returned size is in +”application pixels”, not in ”device pixels” (see +`ScreenExt::get_monitor_scale_factor`). + +# Deprecated since 3.22 + +Use per-monitor information instead # Returns the width of `self` in pixels. - + Gets the width of `self` in millimeters. -Note that on some X servers this value will not be correct. + +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. + +# Deprecated since 3.22 + +Use per-monitor information instead # Returns the width of `self` in millimeters. - + Returns a `glib::List` of ``GdkWindows`` representing the current window stack. @@ -2832,7 +3819,7 @@ its windows unrefed using `gobject::Object::unref` when no longer needed. a list of ``GdkWindows`` for the current window stack, or `None`. - + Returns whether windows with an RGBA visual can reasonably be expected to have their alpha channel drawn correctly on the screen. @@ -2844,7 +3831,7 @@ compositing `self`. Whether windows with RGBA visuals can reasonably be expected to have their alpha channels drawn correctly on the screen. - + Lists the available visuals for the specified `self`. A visual describes a hardware image data format. For example, a visual might support 24-bit color, or 8-bit color, @@ -2856,14 +3843,17 @@ Call `glib::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 - + Determines the name to pass to `Display::open` to get a `Display` with this screen as the default screen. +# Deprecated since 3.22 + + # Returns a newly allocated string, free with `g_free` - + Sets the default font options for the screen. These options will be set on any `pango::Context`’s newly created with `gdk_pango_context_get_for_screen`. Changing the @@ -2872,7 +3862,7 @@ have already been created. ## `options` a `cairo::FontOptions`, or `None` 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 `pango::FontDescription` and cairo units. The default value is 96, meaning that a 10 point @@ -2893,6 +3883,134 @@ the window is scrolled to the right. the scrolling is determined by the delta values in `EventScroll`. See `gdk_event_get_scroll_deltas`. Since: 3.4 + +The `Seat` object represents a collection of input devices +that belong to a user. + +Feature: `v3_20` + +# Implements + +[`SeatExt`](trait.SeatExt.html) + +Trait containing all `Seat` methods. + +Feature: `v3_20` + +# Implementors + +[`Seat`](struct.Seat.html) + +Returns the capabilities this `Seat` currently has. + +Feature: `v3_20` + + +# Returns + +the seat capabilities + +Returns the `Display` this seat belongs to. + +# Returns + +a `Display`. This object is owned by GTK+ + and must not be freed. + +Returns the master device that routes keyboard events. + +Feature: `v3_20` + + +# Returns + +a master `Device` with keyboard + capabilities. This object is owned by GTK+ and must not be freed. + +Returns the master device that routes pointer events. + +Feature: `v3_20` + + +# Returns + +a master `Device` with pointer + capabilities. This object is owned by GTK+ and must not be freed. + +Returns the slave devices that match the given capabilities. + +Feature: `v3_20` + +## `capabilities` +capabilities to get devices for + +# Returns + +A list of ``GdkDevices``. + The list must be freed with `glib::List::free`, the elements are owned + by GDK and must not be freed. + +Grabs the seat so that all events corresponding to the given `capabilities` +are passed to this application until the seat is ungrabbed with `SeatExt::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 `SeatCapabilities::Pointer`, +all other "pointing" capabilities (eg. `SeatCapabilities::Touch`) should +be grabbed too, so the user is able to interact with all of those while +the grab holds, you should thus use `SeatCapabilities::AllPointing` 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 `Window` 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 `EventGrabBroken` +events that are emitted when the grab ends unvoluntarily. + +Feature: `v3_20` + +## `window` +the `Window` which will own the grab +## `capabilities` +capabilities that will be grabbed +## `owner_events` +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. +## `cursor` +the cursor to display while the grab is active. If + this is `None` then the normal cursors are used for + `window` and its descendants, and the cursor for `window` is used + elsewhere. +## `event` +the event that is triggering the grab, or `None` if none + is available. +## `prepare_func` +function to + prepare the window to be grabbed, it can be `None` if `window` is + visible before this call. +## `prepare_func_data` +user data to pass to `prepare_func` + +# Returns + +`GrabStatus::Success` if the grab was successful. + +Releases a grab added through `SeatExt::grab`. + +Feature: `v3_20` + Specifies the kind of modification applied to a setting in a `EventSetting`. @@ -2902,7 +4020,24 @@ 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 + +Feature: `v3_22` + Specifies the visiblity status of a window for a `EventVisibility`. @@ -2914,6 +4049,16 @@ the window is not visible at all. A `Visual` contains information about a particular visual. + +# Implements + +[`VisualExt`](trait.VisualExt.html) + +Trait containing all `Visual` methods. + +# Implementors + +[`Visual`](struct.Visual.html) Get the visual with the most available colors for the default GDK screen. The return value should not be freed. @@ -2977,13 +4122,20 @@ The return value should not be freed. # Returns 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. + +# Deprecated since 3.22 + +Use `VisualExt::get_red_pixel_details` and its variants to + learn about the pixel layout of TrueColor and DirectColor visuals + # Returns The number of significant bits per color value for `self`. - + 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 @@ -2995,25 +4147,40 @@ A pointer to a `guint32` to be filled in, or `None` A pointer to a `gint` to be filled in, or `None` ## `precision` A pointer to a `gint` to be filled in, or `None` - + 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. + +# Deprecated since 3.22 + +This information is not useful + # Returns A `ByteOrder` stating the byte order of `self`. - + Returns the size of a colormap for this visual. +You have to use platform-specific APIs to manipulate colormaps. + +# Deprecated since 3.22 + +This information is not useful, since GDK does not + provide APIs to operate on colormaps. + # Returns The size of a colormap that is suitable for `self`. - + Returns the bit depth of this visual. # Returns The bit depth of this visual. - + 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 @@ -3025,7 +4192,7 @@ A pointer to a `guint32` to be filled in, or `None` A pointer to a `gint` to be filled in, or `None` ## `precision` A pointer to a `gint` to be filled in, or `None` - + 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 @@ -3037,13 +4204,13 @@ A pointer to a `guint32` to be filled in, or `None` A pointer to a `gint` to be filled in, or `None` ## `precision` A pointer to a `gint` to be filled in, or `None` - + Gets the screen to which this visual belongs # Returns the screen to which this visual belongs. - + Returns the type of visual this is (PseudoColor, TrueColor, etc). # Returns @@ -3068,7 +4235,7 @@ Each pixel is an index into a color map that an application. Each pixel value directly contains red, green, - and blue components. Use `Visual::get_red_pixel_details`, etc, + and blue components. Use `VisualExt::get_red_pixel_details`, etc, to obtain information about how the components are assembled into a pixel value. @@ -3078,6 +4245,16 @@ Each pixel value contains red, green, and blue being converted directly. + +# Implements + +[`WindowExt`](trait.WindowExt.html) + +Trait containing all `Window` methods. + +# Implementors + +[`Window`](struct.Window.html) Creates a new `Window` using the attributes from `attributes`. See `WindowAttr` and `WindowAttributesType` for @@ -3103,11 +4280,11 @@ belongs to another application and a `Window` hasn’t been created for it with `gdk_window_foreign_new`) NOTE: For multihead-aware widgets or applications use -`Display::get_window_at_pointer` instead. +`DisplayExt::get_window_at_pointer` instead. # Deprecated since 3.0 -Use `Device::get_window_at_position` instead. +Use `DeviceExt::get_window_at_position` instead. ## `win_x` return location for origin of the window under the pointer ## `win_y` @@ -3132,14 +4309,14 @@ location to store resulting width ## `new_height` location to store resulting height -Calls `Window::process_updates` for all windows (see `Window`) +Calls `WindowExt::process_updates` for all windows (see `Window`) in the application. With update debugging enabled, calls to -`Window::invalidate_region` clear the invalidated region of the +`WindowExt::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 -`Window::process_updates`. The net effect is that you can see +`WindowExt::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. @@ -3154,9 +4331,12 @@ enables this debug option at application startup time. That's usually more useful than calling `Window::set_debug_updates` yourself, though you might want to use this function to enable updates sometime after application startup time. + +# Deprecated since 3.22 + ## `setting` `true` to turn on update debugging - + Adds an event filter to `self`, 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 @@ -3170,15 +4350,54 @@ XFreeEventData() must not be called within `function`. filter callback ## `data` data to pass to filter callback - + Emits a short beep associated to `self` in the appropriate display, if supported. Otherwise, emits a short beep on -the display just as `Display::beep`. - +the display just as `DisplayExt::beep`. + +Indicates that you are beginning the process of redrawing `region` +on `self`, and provides you with a `DrawingContext`. + +If `self` is a top level `Window`, 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 `self`. Then, all +drawing operations performed on `self` will be diverted to the +backing store. When you call `gdk_window_end_frame`, the contents of +the backing store will be copied to `self`, making it visible +on screen. Only the part of `self` 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 +`WindowExt::end_draw_frame`. If you draw to `self` directly without +calling `WindowExt::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 +`WindowExt::begin_draw_frame` and `WindowExt::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 `WindowExt::begin_draw_frame` +explicitly. + +Feature: `v3_22` + +## `region` +a Cairo region + +# Returns + +a `DrawingContext` context that should be + used to draw the contents of the window; the returned context is owned + by GDK. + Begins a window move operation (for a toplevel window). This function assumes that the drag is controlled by the -client pointer device, use `Window::begin_move_drag_for_device` +client pointer device, use `WindowExt::begin_move_drag_for_device` to begin a drag with a different device. ## `button` the button being used to drag, or 0 for a keyboard-initiated drag @@ -3188,7 +4407,7 @@ root window X coordinate of mouse click that began the drag root window Y coordinate of mouse click that began the drag ## `timestamp` 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 @@ -3204,58 +4423,66 @@ root window X coordinate of mouse click that began the drag root window Y coordinate of mouse click that began the drag ## `timestamp` timestamp of mouse click that began the drag - -A convenience wrapper around `Window::begin_paint_region` which + +A convenience wrapper around `WindowExt::begin_paint_region` which creates a rectangular region for you. See -`Window::begin_paint_region` for details. +`WindowExt::begin_paint_region` for details. + +# Deprecated since 3.22 + +Use `WindowExt::begin_draw_frame` instead ## `rectangle` 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 `self`. Then, all drawing operations performed on `self` will be diverted to the -backing store. When you call `Window::end_paint`, the backing +backing store. When you call `WindowExt::end_paint`, the backing store will be copied to `self`, making it visible onscreen. Only the part of `self` 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 -`Window::end_paint`. If you draw to `self` directly without -calling `Window::begin_paint_region`, the user may see flicker +`WindowExt::end_paint`. If you draw to `self` directly without +calling `WindowExt::begin_paint_region`, the user may see flicker as individual drawing operations are performed in sequence. The clipping and background-initializing features of -`Window::begin_paint_region` are conveniences for the +`WindowExt::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 -`Window::begin_paint_region` and `Window::end_paint` around +`WindowExt::begin_paint_region` and `WindowExt::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 `EventExpose` 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 -`Window::begin_paint_region`. (You can disable the automatic +`WindowExt::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 `Window::end_paint`, the backing stores are pushed onto -a stack. `Window::end_paint` copies the topmost backing store +matching `WindowExt::end_paint`, the backing stores are pushed onto +a stack. `WindowExt::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 -`Window::end_paint` is required for each call to -`Window::begin_paint_region`. +`WindowExt::end_paint` is required for each call to +`WindowExt::begin_paint_region`. + +# Deprecated since 3.22 + +Use `WindowExt::begin_draw_frame` instead ## `region` 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 `Window::begin_resize_drag_for_device` +client pointer device, use `WindowExt::begin_resize_drag_for_device` to begin a drag with a different device. ## `edge` the edge or corner from which the drag is started @@ -3267,7 +4494,7 @@ root window X coordinate of mouse click that began the drag root window Y coordinate of mouse click that began the drag ## `timestamp` 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 @@ -3286,21 +4513,21 @@ root window X coordinate of mouse click that began the drag root window Y coordinate of mouse click that began the drag ## `timestamp` timestamp of mouse click that began the drag (use `gdk_event_get_time`) - + Does nothing, present only for compatiblity. # Deprecated since 3.8 this function is no longer needed - + Transforms window coordinates from a parent window to a child window, where the parent window is the normal parent as returned by -`Window::get_parent` for normal windows, and the window's +`WindowExt::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 `Window::get_position` from the parent coordinates. +the return values of `WindowExt::get_position` from the parent coordinates. For offscreen windows however (which can be arbitrarily transformed), this function calls the `Window`::from-embedder: signal to translate the coordinates. @@ -3308,7 +4535,7 @@ the coordinates. You should always use this function when writing generic code that walks down a window hierarchy. -See also: `Window::coords_to_parent` +See also: `WindowExt::coords_to_parent` ## `parent_x` X coordinate in parent’s coordinate system ## `parent_y` @@ -3317,15 +4544,15 @@ Y coordinate in parent’s coordinate system return location for X coordinate in child’s coordinate system ## `y` 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 -`Window::get_parent` for normal windows, and the window's +`WindowExt::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 `Window::get_position` to the child coordinates. +the return values of `WindowExt::get_position` to the child coordinates. For offscreen windows however (which can be arbitrarily transformed), this function calls the `Window`::to-embedder: signal to translate the coordinates. @@ -3333,7 +4560,7 @@ the coordinates. You should always use this function when writing generic code that walks up a window hierarchy. -See also: `Window::coords_from_parent` +See also: `WindowExt::coords_from_parent` ## `x` X coordinate in child’s coordinate system ## `y` @@ -3344,7 +4571,7 @@ in parent’s coordinate system, or `None` ## `parent_y` return location for Y coordinate in parent’s coordinate system, or `None` - + Creates a new `GLContext` matching the framebuffer format to the visual of the `Window`. The context is disconnected from any particular window or surface. @@ -3352,7 +4579,7 @@ is disconnected from any particular window or surface. If the creation of the `GLContext` failed, `error` will be set. Before using the returned `GLContext`, you will need to -call `GLContext::make_current` or `GLContext::realize`. +call `GLContextExt::make_current` or `GLContextExt::realize`. Feature: `v3_16` @@ -3361,13 +4588,33 @@ Feature: `v3_16` the newly created `GLContext`, or `None` on error - + Create a new image surface that is efficient to draw on the given `self`. 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 `self`, 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 `self` you can +use: + + +```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); +``` + Feature: `v3_10` ## `format` @@ -3388,7 +4635,7 @@ 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. - + Create a new surface that is as compatible as possible with the given `self`. For example the new surface will have the same fallback resolution and font options as `self`. Generally, the new @@ -3414,35 +4661,48 @@ 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. - + Attempt to deiconify (unminimize) `self`. On X11 the window manager may choose to ignore the request to deiconify. When using GTK+, use `gtk_window_deiconify` instead of the `Window` variant. Or better yet, you probably want to use `gtk_window_present`, which raises the window, focuses it, unminimizes it, and puts it on the current desktop. - + Destroys the window system resources associated with `self` and decrements `self`'s reference count. The window system resources for all children of `self` 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. - + Does nothing, present only for compatiblity. # Deprecated since 3.8 this function is no longer needed - + +Indicates that the drawing of the contents of `self` started with +`gdk_window_begin_frame` has been completed. + +This function will take care of destroying the `DrawingContext`. + +It is an error to call this function without a matching +`gdk_window_begin_frame` first. + +Feature: `v3_22` + +## `context` +the `DrawingContext` created by `WindowExt::begin_draw_frame` + Indicates that the backing store created by the most recent call -to `Window::begin_paint_region` should be copied onscreen and +to `WindowExt::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 -`Window::begin_paint_region` for full details. +`WindowExt::begin_paint_region` for full details. It is an error to call this function without a matching -`Window::begin_paint_region` first. - +`WindowExt::begin_paint_region` first. + Tries to ensure that there is a window-system native window for this `Window`. This may fail in some situations, returning `false`. @@ -3453,23 +4713,23 @@ Some backends may not support native child windows. # Returns `true` if the window has a native window, `false` otherwise - + This function does nothing. # Deprecated since 3.14 - + Sets keyboard focus to `self`. In most cases, `gtk_window_present` should be used on a ``GtkWindow``, rather than calling this function. ## `timestamp` 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 `Window::thaw_toplevel_updates_libgtk_only` is called. If -`Window::freeze_toplevel_updates_libgtk_only` +again when `WindowExt::thaw_toplevel_updates_libgtk_only` is called. If +`WindowExt::freeze_toplevel_updates_libgtk_only` has been called more than once, -`Window::thaw_toplevel_updates_libgtk_only` must be called +`WindowExt::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 @@ -3478,13 +4738,13 @@ for use by GTK+. # Deprecated since 3.16 This symbol was never meant to be used outside of GTK+ - + Temporarily freezes a window such that it won’t receive expose events. The window will begin receiving expose events again when -`Window::thaw_updates` is called. If `Window::freeze_updates` -has been called more than once, `Window::thaw_updates` must be called +`WindowExt::thaw_updates` is called. If `WindowExt::freeze_updates` +has been called more than once, `WindowExt::thaw_updates` must be called an equal number of times to begin processing exposes. - + Moves the window into fullscreen mode. This means the window covers the entire screen and is above any panels or task bars. @@ -3498,27 +4758,38 @@ 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. - + +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. +## `monitor` +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. - + Determines whether or not the desktop environment shuld be hinted that the window does not want to receive input focus. # Returns whether or not the window should receive input focus. - + Gets the pattern used to clear the background on `self`. If `self` does not have its own background and reuses the parent's, `None` is returned and you’ll have to query it yourself. +# Deprecated since 3.22 + +Don't use this function + # Returns The pattern to use for the background or `None` to use the parent’s background. - + Gets the list of children of `self` known to GDK. This function only returns children created via GDK, so for example it’s useless when used with the root window; @@ -3531,7 +4802,7 @@ list need not be. list of child windows inside `self` - + Gets the list of children of `self` known to GDK with a particular `user_data` set on it. @@ -3550,7 +4821,7 @@ user data to look for list of child windows inside `self` - + 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, @@ -3561,10 +4832,10 @@ primitives. a `cairo::Region`. This must be freed with `cairo_region_destroy` when you are done. - + Determines whether `self` is composited. -See `Window::set_composited`. +See `WindowExt::set_composited`. # Deprecated since 3.16 @@ -3574,7 +4845,7 @@ Compositing is an outdated technology that # Returns `true` if the window is composited. - + Retrieves a `Cursor` pointer for the cursor currently set on the specified `Window`, or `None`. If the return value is `None` then there is no custom cursor set on the specified window, and it is @@ -3584,18 +4855,18 @@ using the cursor for its parent window. a `Cursor`, or `None`. The returned object is owned by the `Window` and should not be - unreferenced directly. Use `Window::set_cursor` to unset the + unreferenced directly. Use `WindowExt::set_cursor` to unset the cursor of the window - + Returns the decorations set on the `Window` with -`Window::set_decorations`. +`WindowExt::set_decorations`. ## `decorations` The window decorations will be written here # Returns `true` if the window has decorations set, `false` otherwise. - + Retrieves a `Cursor` pointer for the `device` currently set on the specified `Window`, or `None`. If the return value is `None` then there is no custom cursor set on the specified window, and it is @@ -3607,9 +4878,9 @@ a master, pointer `Device`. a `Cursor`, or `None`. The returned object is owned by the `Window` and should not be - unreferenced directly. Use `Window::set_cursor` to unset the + unreferenced directly. Use `WindowExt::set_cursor` to unset the cursor of the window - + Returns the event mask for `self` corresponding to an specific device. ## `device` a `Device`. @@ -3617,12 +4888,12 @@ a `Device`. # Returns device event mask for `self` - + Obtains the current device position and modifier state. The position is given in coordinates relative to the upper left corner of `self`. -Use `Window::get_device_position_double` if you need subpixel precision. +Use `WindowExt::get_device_position_double` if you need subpixel precision. ## `device` pointer `Device` to query to. ## `x` @@ -3635,9 +4906,9 @@ return location for the modifier mask, or `None`. # Returns The window underneath `device` -(as with `Device::get_window_at_position`), or `None` if the +(as with `DeviceExt::get_window_at_position`), or `None` if the window is not known to GDK. - + Obtains the current device position in doubles and modifier state. The position is given in coordinates relative to the upper left corner of `self`. @@ -3656,15 +4927,15 @@ return location for the modifier mask, or `None`. # Returns The window underneath `device` -(as with `Device::get_window_at_position`), or `None` if the +(as with `DeviceExt::get_window_at_position`), or `None` if the window is not known to GDK. - + Gets the `Display` associated with a `Window`. # Returns the `Display` associated with `self` - + Finds out the DND protocol supported by a window. ## `target` location of the window @@ -3674,9 +4945,9 @@ location of the window # Returns the supported DND protocol. - + Obtains the parent of `self`, as known to GDK. Works like -`Window::get_parent` for normal windows, but returns the +`WindowExt::get_parent` for normal windows, but returns the window’s embedder for offscreen windows. See also: `gdk_offscreen_window_get_embedder` @@ -3684,18 +4955,18 @@ See also: `gdk_offscreen_window_get_embedder` # Returns effective parent of `self` - + Gets the toplevel window that’s an ancestor of `self`. -Works like `Window::get_toplevel`, but treats an offscreen window's -embedder as its parent, using `Window::get_effective_parent`. +Works like `WindowExt::get_toplevel`, but treats an offscreen window's +embedder as its parent, using `WindowExt::get_effective_parent`. See also: `gdk_offscreen_window_get_embedder` # Returns the effective toplevel window containing `self` - + Get the current event compression setting for this window. Feature: `v3_12` @@ -3704,14 +4975,14 @@ Feature: `v3_12` # Returns `true` if motion events will be compressed - + Gets the event mask for `self` for all master input devices. See -`Window::set_events`. +`WindowExt::set_events`. # Returns event mask for `self` - + Determines whether or not the desktop environment should be hinted that the window does not want to receive input focus when it is mapped. @@ -3719,7 +4990,7 @@ 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. - + 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. @@ -3730,14 +5001,14 @@ Feature: `v3_8` # Returns the frame clock - + 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 `Window::get_origin`. +the frame) in root window coordinates, use `WindowExt::get_origin`. ## `rect` rectangle to fill with bounding box of the window frame - + Obtains the `FullscreenMode` of the `self`. Feature: `v3_8` @@ -3746,7 +5017,7 @@ Feature: `v3_8` # Returns The `FullscreenMode` applied to the window when fullscreen. - + Any of the return location arguments to this function may be `None`, if you aren’t interested in getting the value of that field. @@ -3758,14 +5029,14 @@ root window (screen-size background window). On the X11 platform, the geometry is obtained from the X server, so reflects the latest position of `self`; this may be out-of-sync with the position of `self` delivered in the most-recently-processed -`EventConfigure`. `Window::get_position` in contrast gets the +`EventConfigure`. `WindowExt::get_position` in contrast gets the position from the most recent configure event. Note: If `self` is not a toplevel, it is much better -to call `Window::get_position`, `Window::get_width` and -`Window::get_height` instead, because it avoids the roundtrip to +to call `WindowExt::get_position`, `WindowExt::get_width` and +`WindowExt::get_height` instead, because it avoids the roundtrip to the X server and because these functions support the full 32-bit -coordinate space, whereas `Window::get_geometry` is restricted to +coordinate space, whereas `WindowExt::get_geometry` is restricted to the 16-bit coordinates of X11. ## `x` return location for X coordinate of window (relative to its parent) @@ -3775,13 +5046,13 @@ return location for Y coordinate of window (relative to its parent) return location for width of window ## `height` return location for height of window - -Returns the group leader window for `self`. See `Window::set_group`. + +Returns the group leader window for `self`. See `WindowExt::set_group`. # Returns the group leader window for `self` - + Returns the height of the given `self`. On the X11 platform the returned size is the size reported in the @@ -3791,17 +5062,17 @@ size on the X server. # Returns The height of `self` - + Determines whether or not the window manager is hinted that `self` has modal behaviour. # Returns whether or not the window has the modal hint set. - + Obtains the position of a window in root window coordinates. -(Compare with `Window::get_position` and -`Window::get_geometry` which return the position of a window +(Compare with `WindowExt::get_position` and +`WindowExt::get_geometry` which return the position of a window relative to its parent window.) ## `x` return location for X coordinate @@ -3811,7 +5082,7 @@ return location for Y coordinate # Returns not meaningful, ignore - + Obtains the parent of `self`, as known to GDK. Does not query the X server; thus this returns the parent as passed to `Window::new`, not the actual parent. This should never matter unless you’re using @@ -3819,22 +5090,30 @@ 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 `Window::get_effective_parent` when +Note that you should use `WindowExt::get_effective_parent` when writing generic code that walks up a window hierarchy, because -`Window::get_parent` will most likely not do what you expect if +`WindowExt::get_parent` will most likely not do what you expect if there are offscreen windows in the hierarchy. # Returns parent of `self` - + +Returns whether input to the window is passed through to the window +below. + +See `WindowExt::set_pass_through` for details + +Feature: `v3_18` + + Obtains the current pointer position and modifier state. The position is given in coordinates relative to the upper left corner of `self`. # Deprecated since 3.0 -Use `Window::get_device_position` instead. +Use `WindowExt::get_device_position` instead. ## `x` return location for X coordinate of pointer or `None` to not return the X coordinate @@ -3850,10 +5129,10 @@ return location for modifier mask or `None` to not return the the window containing the pointer (as with `Window::at_pointer`), or `None` if the window containing the pointer isn’t known to GDK - + Obtains the position of the window as reported in the most-recently-processed `EventConfigure`. Contrast with -`Window::get_geometry` which queries the X server for the +`WindowExt::get_geometry` which queries the X server for the current window position, regardless of which events have been received or processed. @@ -3862,10 +5141,10 @@ The position coordinates are relative to the window’s parent window. X coordinate of window ## `y` Y coordinate of window - + Obtains the position of a window position in root window coordinates. This is similar to -`Window::get_origin` but allows you to pass +`WindowExt::get_origin` but allows you to pass in any position in the window, not just the origin. ## `x` X coordinate in window @@ -3875,14 +5154,14 @@ Y coordinate in window return location for X coordinate ## `root_y` return location for Y coordinate - + Obtains the top-left corner of the window manager frame in root window coordinates. ## `x` return location for X position of window frame ## `y` 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). @@ -3902,13 +5181,13 @@ Feature: `v3_10` # Returns the scale factor - + Gets the `Screen` associated with a `Window`. # Returns the `Screen` associated with `self` - + Returns the event mask for `self` corresponding to the device class specified by `source`. ## `source` @@ -3917,58 +5196,58 @@ a `InputSource` to define the source class. # Returns source event mask for `self` - + Gets the bitwise OR of the currently active window state flags, from the `WindowState` enumeration. # Returns window state bitfield - + Returns `true` if the window is aware of the existence of multiple devices. # Returns `true` if the window handles multidevice features. - + Gets the toplevel window that’s an ancestor of `self`. Any window type but `WindowType::Child` is considered a toplevel window, as is a `WindowType::Child` window that has a root window as parent. -Note that you should use `Window::get_effective_toplevel` when +Note that you should use `WindowExt::get_effective_toplevel` when you want to get to a window’s toplevel as seen on screen, because -`Window::get_toplevel` will most likely not do what you expect +`WindowExt::get_toplevel` will most likely not do what you expect if there are offscreen windows in the hierarchy. # Returns the toplevel window containing `self` - + This function returns the type hint set for a window. # Returns The type hint set for `self` - + Transfers ownership of the update area from `self` to the caller of the function. That is, after calling this function, `self` will no longer have an invalid/dirty region; the update area is removed from `self` and handed to you. If a window has no update area, -`Window::get_update_area` returns `None`. You are responsible for +`WindowExt::get_update_area` returns `None`. You are responsible for calling `cairo_region_destroy` on the returned region if it’s non-`None`. # Returns the update area for `self` - + Retrieves the user data for `self`, which is normally the widget -that `self` belongs to. See `Window::set_user_data`. +that `self` belongs to. See `WindowExt::set_user_data`. ## `data` return location for user data - + Computes the region of the `self` 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 @@ -3978,13 +5257,13 @@ is visible. a `cairo::Region`. This must be freed with `cairo_region_destroy` when you are done. - + Gets the `Visual` describing the pixel format of `self`. # Returns a `Visual` - + Returns the width of the given `self`. On the X11 platform the returned size is the size reported in the @@ -3994,32 +5273,32 @@ size on the X server. # Returns The width of `self` - + Gets the type of the window. See `WindowType`. # Returns type of window - + Checks whether the window has a native window or not. Note that -you can use `Window::ensure_native` if a native window is needed. +you can use `WindowExt::ensure_native` if a native window is needed. # Returns `true` if the `self` has a native window, `false` otherwise. - + 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`. - + Asks to iconify (minimize) `self`. 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 `self` is a toplevel window. - -Like `Window::shape_combine_region`, but the shape applies + +Like `WindowExt::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 `self`. @@ -4041,10 +5320,10 @@ region of window to be non-transparent X position of `shape_region` in `self` coordinates ## `offset_y` Y position of `shape_region` in `self` coordinates - + Adds `region` to the update area for `self`. The update area is the region that needs to be redrawn, or “dirty region.” The call -`Window::process_updates` sends one or more expose events to the +`WindowExt::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 `self` in response to those expose events. @@ -4065,19 +5344,19 @@ function to use to decide if to recurse to a child, `None` means never recurse. ## `user_data` data passed to `child_func` - -A convenience wrapper around `Window::invalidate_region` which + +A convenience wrapper around `WindowExt::invalidate_region` which invalidates a rectangular region. See -`Window::invalidate_region` for details. +`WindowExt::invalidate_region` for details. ## `rect` rectangle to invalidate or `None` to invalidate the whole window ## `invalidate_children` whether to also invalidate child windows - + Adds `region` to the update area for `self`. The update area is the region that needs to be redrawn, or “dirty region.” The call -`Window::process_updates` sends one or more expose events to the +`WindowExt::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 `self` in response to those expose events. @@ -4096,25 +5375,25 @@ fine grained control over which children are invalidated. a `cairo::Region` ## `invalidate_children` `true` to also invalidate child windows - + Check to see if a window is destroyed.. # Returns `true` if the window is destroyed - + Determines whether or not the window is an input only window. # Returns `true` if `self` is input only - + Determines whether or not the window is shaped. # Returns `true` if `self` is shaped - + 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 @@ -4123,27 +5402,27 @@ window.) # Returns `true` if the window is viewable - -Checks whether the window has been mapped (with `Window::show` or -`Window::show_unraised`). + +Checks whether the window has been mapped (with `WindowExt::show` or +`WindowExt::show_unraised`). # Returns `true` if the window is mapped - + Lowers `self` to the bottom of the Z-order (stacking order), so that other windows with the same parent window appear above `self`. This is true whether or not the other windows are visible. If `self` is a toplevel, the window manager may choose to deny the -request to move the window in the Z-order, `Window::lower` only +request to move the window in the Z-order, `WindowExt::lower` only requests the restack, does not guarantee it. -Note that `Window::show` raises the window again, so don’t call this -function before `Window::show`. (Try `Window::show_unraised`.) - -If you call this during a paint (e.g. between `Window::begin_paint_region` -and `Window::end_paint` then GDK will mark the current clip region of the +Note that `WindowExt::show` raises the window again, so don’t call this +function before `WindowExt::show`. (Try `WindowExt::show_unraised`.) + +If you call this during a paint (e.g. between `WindowExt::begin_paint_region` +and `WindowExt::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. @@ -4155,7 +5434,7 @@ Feature: `v3_16` ## `cr` a `cairo::Context` - + Maximizes the window. If the window was already maximized, then this function does nothing. @@ -4167,38 +5446,38 @@ 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. - + Merges the input shape masks for any child windows into the input shape mask for `self`. i.e. the union of all input masks for `self` and its children will become the new input mask -for `self`. See `Window::input_shape_combine_region`. +for `self`. See `WindowExt::input_shape_combine_region`. -This function is distinct from `Window::set_child_input_shapes` +This function is distinct from `WindowExt::set_child_input_shapes` because it includes `self`’s input shape mask in the set of shapes to be merged. - + Merges the shape masks for any child windows into the shape mask for `self`. i.e. the union of all masks for `self` and its children will become the new mask -for `self`. See `Window::shape_combine_region`. +for `self`. See `WindowExt::shape_combine_region`. -This function is distinct from `Window::set_child_shapes` +This function is distinct from `WindowExt::set_child_shapes` because it includes `self`’s shape mask in the set of shapes to be merged. - + 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 `Window::move_resize` +If you’re also planning to resize the window, use `WindowExt::move_resize` to both move and resize simultaneously, for a nicer visual effect. ## `x` X coordinate relative to window’s parent ## `y` Y coordinate relative to window’s parent - + Move the part of `self` 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. @@ -4210,11 +5489,11 @@ The `cairo::Region` to move Amount to move in the X direction ## `dy` Amount to move in the Y direction - -Equivalent to calling `Window::move` and `Window::resize`, + +Equivalent to calling `WindowExt::move` and `WindowExt::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 `Window::move_resize`.) +move, then resize, if you don’t use `WindowExt::move_resize`.) ## `x` new X position relative to window’s parent ## `y` @@ -4223,18 +5502,18 @@ new Y position relative to window’s parent new width ## `height` new height - -Like `Window::get_children`, but does not copy the list of + +Like `WindowExt::get_children`, but does not copy the list of children, so the list does not need to be freed. # Returns a reference to the list of child windows in `self` - + Sends one or more expose events to `self`. The areas in each expose event will cover the entire update area for the window (see -`Window::invalidate_region` for details). Normally GDK calls +`WindowExt::invalidate_region` for details). Normally GDK calls `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 @@ -4242,23 +5521,23 @@ case, where GDK delivers them in an idle handler). Occasionally this is useful to produce nicer scrolling behavior, for example. ## `update_children` whether to also process updates for child windows - + Raises `self` to the top of the Z-order (stacking order), so that other windows with the same parent window appear below `self`. This is true whether or not the windows are visible. If `self` is a toplevel, the window manager may choose to deny the -request to move the window in the Z-order, `Window::raise` only +request to move the window in the Z-order, `WindowExt::raise` only requests the restack, does not guarantee it. - + Registers a window as a potential drop destination. - -Remove a filter previously added with `Window::add_filter`. + +Remove a filter previously added with `WindowExt::add_filter`. ## `function` previously-added filter function ## `data` user data for previously-added filter function - + Reparents `self` into the given `new_parent`. The window being reparented will be unmapped as a side effect. ## `new_parent` @@ -4267,20 +5546,20 @@ new parent to move `self` into X location inside the new parent ## `y` Y location inside the new parent - + Resizes `self`; 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 `Window::move_resize` +If you’re also planning to move the window, use `WindowExt::move_resize` to both move and resize simultaneously, for a nicer visual effect. ## `width` new width of the window ## `height` new height of the window - + Changes the position of `self` in the Z-order (stacking order), so that it is above `sibling` (if `above` is `true`) or below `sibling` (if `above` is `false`). @@ -4289,13 +5568,13 @@ If `sibling` is `None`, then this either raises (if `above` is `true`) or lowers the window. If `self` is a toplevel, the window manager may choose to deny the -request to move the window in the Z-order, `Window::restack` only +request to move the window in the Z-order, `WindowExt::restack` only requests the restack, does not guarantee it. ## `sibling` a `Window` that is a sibling of `self`, or `None` ## `above` a boolean - + Scroll the contents of `self`, both pixels and children, by the given amount. `self` itself does not move. Portions of the window that the scroll operation brings in from offscreen areas are @@ -4311,7 +5590,7 @@ artifacts and unnecessary invalidations. Amount to scroll in the X direction ## `dy` 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. @@ -4319,7 +5598,7 @@ On X, it is the responsibility of the window manager to interpret this hint. ICCCM-compliant window manager usually respect it. ## `accept_focus` `true` if the window should receive input focus - + Sets the background color of `self`. However, when using GTK+, influence the background of a widget @@ -4327,14 +5606,12 @@ 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. -See also `Window::set_background_pattern`. - # Deprecated since 3.4 -Use `Window::set_background_rgba` instead. +Don't use this function ## `color` a `Color` - + Sets the background of `self`. A background of `None` means that the window will inherit its @@ -4342,25 +5619,33 @@ background from its parent window. The windowing system will normally fill a window with its background when the window is obscured then exposed. + +# Deprecated since 3.22 + +Don't use this function ## `pattern` a pattern to use, or `None` - + Sets the background color of `self`. -See also `Window::set_background_pattern`. +See also `WindowExt::set_background_pattern`. + +# Deprecated since 3.22 + +Don't use this function ## `rgba` a `RGBA` color - + Sets the input shape mask of `self` to the union of input shape masks for all children of `self`, ignoring the input shape mask of `self` -itself. Contrast with `Window::merge_child_input_shapes` which includes +itself. Contrast with `WindowExt::merge_child_input_shapes` which includes the input shape mask of `self` in the masks to be merged. - + Sets the shape mask of `self` to the union of shape masks for all children of `self`, ignoring the shape mask of `self` -itself. Contrast with `Window::merge_child_shapes` which includes +itself. Contrast with `WindowExt::merge_child_shapes` which includes the shape mask of `self` in the masks to be merged. - + Sets a `Window` as composited, or unsets it. Composited windows do not automatically have their contents drawn to the screen. Drawing is redirected to an offscreen buffer @@ -4370,7 +5655,7 @@ 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 -`Window::set_opacity` if you need translucent toplevel +`WindowExt::set_opacity` if you need translucent toplevel windows. An additional effect of this call is that the area of this @@ -4380,7 +5665,7 @@ 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 `Display::supports_composite` to check if +You must call `DisplayExt::supports_composite` to check if setting a window as composited is supported before attempting to do so. @@ -4390,19 +5675,19 @@ Compositing is an outdated technology that only ever worked on X11. ## `composited` `true` to set the window as composited - + Sets the default mouse pointer for a `Window`. Note that `cursor` must be for the same display as `self`. Use `Cursor::new_for_display` or `Cursor::new_from_pixbuf` to create the cursor. To make the cursor invisible, use `CursorType::BlankCursor`. -Passing `None` for the `cursor` argument to `Window::set_cursor` means +Passing `None` for the `cursor` argument to `WindowExt::set_cursor` means that `self` will use the cursor of its parent window. Most windows should use this default. ## `cursor` a cursor - + “Decorations” are the features the window manager adds to a toplevel `Window`. This function sets the traditional Motif window manager hints that tell the window manager which decorations you would like your window to have. @@ -4419,18 +5704,18 @@ Most window managers honor a decorations hint of 0 to disable all decorations, but very few honor all possible combinations of bits. ## `decorations` decoration hint mask - + Sets a specific `Cursor` for a given device when it gets inside `self`. Use `Cursor::new_for_display` or `Cursor::new_from_pixbuf` to create the cursor. To make the cursor invisible, use `CursorType::BlankCursor`. Passing -`None` for the `cursor` argument to `Window::set_cursor` means that +`None` for the `cursor` argument to `WindowExt::set_cursor` means that `self` will use the cursor of its parent window. Most windows should use this default. ## `device` a master, pointer `Device` ## `cursor` a `Cursor` - + Sets the event mask for a given device (Normally a floating device, not attached to any visible pointer) to `self`. For example, an event mask including `EventMask::ButtonPressMask` means the window should report button @@ -4442,7 +5727,7 @@ See the [input handling overview][event-masks] for details. `Device` to enable events for. ## `event_mask` event mask for `self` - + 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. @@ -4456,7 +5741,7 @@ Feature: `v3_12` ## `event_compression` `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 `EventMask::ButtonPressMask` means the window should report button @@ -4466,7 +5751,7 @@ press events. The event mask is the bitwise OR of values from the See the [input handling overview][event-masks] for details. ## `event_mask` event mask for `self` - + 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 @@ -4477,7 +5762,7 @@ this hint. Window managers following the freedesktop.org window manager extension specification should respect it. ## `focus_on_map` `true` if the window should receive input focus when mapped - + Specifies whether the `self` should span over all monitors (in a multi-head setup) or only the current monitor when in fullscreen mode. @@ -4500,7 +5785,7 @@ Feature: `v3_8` ## `mode` fullscreen mode - + Sets hints about the window management functions to make available via buttons on the window frame. @@ -4516,7 +5801,7 @@ it doesn’t include `WMFunction::All`, it indicates which functions to enable. ## `functions` bitmask of operations to allow on `self` - + Sets the geometry hints for `self`. 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 `None`. @@ -4526,12 +5811,12 @@ 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 `Window::resize` or -`Window::move_resize`. +constrain programatic resizing via `WindowExt::resize` or +`WindowExt::move_resize`. Note that on X11, this effect has no effect on windows of type `WindowType::Temp` or windows where override redirect -has been turned on via `Window::set_override_redirect` +has been turned on via `WindowExt::set_override_redirect` since these windows are not resizable by the user. Since you can’t count on the windowing system doing the @@ -4542,7 +5827,7 @@ appropriate sizes. geometry hints ## `geom_mask` bitmask indicating fields of `geometry` to pay attention to - + Sets the group leader window for `self`. By default, GDK sets the group leader for all toplevel windows to a global window implicitly created by GDK. With this function @@ -4555,7 +5840,7 @@ application at once. You should only set a non-default group window if your application pretends to be multiple applications. ## `leader` group leader window, or `None` 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 @@ -4563,23 +5848,27 @@ 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. ## `pixbufs` 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-`None` `name`, calls to `Window::set_title` +After calling this with a non-`None` `name`, calls to `WindowExt::set_title` will not update the icon title. Using `None` for `name` unsets the icon title; further calls to -`Window::set_title` will again update the icon title as well. +`WindowExt::set_title` will again update the icon title as well. + +Note that some platforms don't support window icons. ## `name` 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. @@ -4594,7 +5883,7 @@ Feature: `v3_10` ## `handler` a ``GdkWindowInvalidateHandlerFunc`` callback function - + Set if `self` must be kept above other windows. If the window was already above, then this function does nothing. @@ -4606,7 +5895,7 @@ But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. ## `setting` whether to keep `self` above other windows - + Set if `self` must be kept below other windows. If the window was already below, then this function does nothing. @@ -4618,17 +5907,17 @@ But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. ## `setting` whether to keep `self` 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 `Window::set_transient_for` +previously called `WindowExt::set_transient_for` ## `modal` `true` if the window is modal, `false` otherwise. - + Set `self` 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.) @@ -4644,13 +5933,13 @@ for your widgets. For child windows this function only works for non-native windows. -For setting up per-pixel alpha topelevels, see `Screen::get_rgba_visual`, -and for non-toplevels, see `Window::set_composited`. +For setting up per-pixel alpha topelevels, see `ScreenExt::get_rgba_visual`, +and for non-toplevels, see `WindowExt::set_composited`. Support for non-toplevel windows was added in 3.8. ## `opacity` 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, @@ -4669,7 +5958,7 @@ Feature: `v3_10` ## `region` a region, or `None` - + 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 @@ -4680,7 +5969,31 @@ windows, such as popup menus. ``GtkMenu`` uses an override redirect window in its implementation, for example. ## `override_redirect` `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 `self`. 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. + +Feature: `v3_18` + +## `pass_through` +a boolean + When using GTK+, typically you should use `gtk_window_set_role` instead of this low-level function. @@ -4695,7 +6008,7 @@ you use for the role, as long as you have a different role for each non-interchangeable kind of window. ## `role` 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 @@ -4716,27 +6029,27 @@ The right extent The top extent ## `bottom` 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 `Window::set_type_hint` +window’s semantic type as specified with `WindowExt::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. ## `skips_pager` `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 -`Window::set_type_hint` already fully describes the window, this +`WindowExt::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. ## `skips_taskbar` `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 @@ -4745,12 +6058,12 @@ after this call, and devices being attached/detached. a `InputSource` to define the source class. ## `event_mask` event mask for `self` - + When using GTK+, typically you should use `gtk_window_set_startup_id` instead of this low-level function. ## `startup_id` 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 @@ -4766,22 +6079,22 @@ static gravities haven't worked on anything but X11 # Returns `false` - + This function will enable multidevice features in `self`. Multidevice aware windows will need to handle properly multiple, per device enter/leave events, device grabs and grab ownerships. ## `support_multidevice` `true` to enable multidevice support in `self`. - + 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 `Window::set_icon_name`), the icon name will be set to +(using `WindowExt::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 `None`. ## `title` title of `self` - + Indicates to the window manager that `self` is a transient dialog associated with the application window `parent`. This allows the window manager to do things like center `self` on `parent` and @@ -4791,7 +6104,7 @@ See `gtk_window_set_transient_for` if you’re using ``GtkWindow`` or ``GtkDialog``. ## `parent` another toplevel `Window` - + 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 @@ -4800,12 +6113,12 @@ of the window. The hint must be set before the window is mapped. ## `hint` A hint of the function this window will have - + Toggles whether a window needs the user's urgent attention. ## `urgent` `true` if the window is urgent - + For most purposes this function is deprecated in favor of `gobject::Object::set_data`. However, for historical reasons GTK+ stores the ``GtkWidget`` that owns a `Window` as user data on the @@ -4815,7 +6128,7 @@ and the user data for the window is non-`None`, GTK+ will assume the user data is a ``GtkWidget``, and forward the event to that widget. ## `user_data` user data - + Makes pixels in `self` outside `shape_region` be transparent, so that the window may be nonrectangular. @@ -4836,25 +6149,25 @@ region of window to be non-transparent X position of `shape_region` in `self` coordinates ## `offset_y` Y position of `shape_region` in `self` coordinates - -Like `Window::show_unraised`, but also raises the window to the + +Like `WindowExt::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 `Window::hide`. +is `WindowExt::hide`. When implementing a ``GtkWidget``, you should call this function on the widget's `Window` as part of the “map” method. - + Shows a `Window` onscreen, but does not modify its stacking -order. In contrast, `Window::show` will raise the window +order. In contrast, `WindowExt::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). - + 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 @@ -4869,7 +6182,7 @@ a ``GdkEvent`` to show the menu for # Returns `true` if the window menu was shown and `false` otherwise. - + “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.) @@ -4879,9 +6192,9 @@ 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. - + Thaws a window frozen with -`Window::freeze_toplevel_updates_libgtk_only`. +`WindowExt::freeze_toplevel_updates_libgtk_only`. This function is not part of the GDK public API and is only for use by GTK+. @@ -4889,9 +6202,9 @@ for use by GTK+. # Deprecated since 3.16 This symbol was never meant to be used outside of GTK+ - -Thaws a window frozen with `Window::freeze_updates`. - + +Thaws a window frozen with `WindowExt::freeze_updates`. + Moves the window out of fullscreen mode. If the window was not fullscreen, does nothing. @@ -4902,7 +6215,7 @@ 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. - + Unmaximizes the window. If the window wasn’t maximized, then this function does nothing. @@ -4914,12 +6227,12 @@ 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. - -Reverse operation for `Window::stick`; see `Window::stick`, + +Reverse operation for `WindowExt::stick`; see `WindowExt::stick`, and `gtk_window_unstick`. - + Withdraws a window (unmaps it and asks the window manager to forget about it). -This function is not really useful as `Window::hide` automatically +This function is not really useful as `WindowExt::hide` automatically withdraws toplevel windows before hiding them. Determines a window edge or corner. diff --git a/gio/vendor.md b/gio/vendor.md new file mode 100644 index 00000000..31d96201 --- /dev/null +++ b/gio/vendor.md @@ -0,0 +1,8311 @@ + + +`Action` represents a single named action. + +The main interface to an action is that it can be activated with +`Action::activate`. This results in the 'activate' signal being +emitted. An activation has a `glib::Variant` parameter (which may be +`None`). 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 `Action::change_state`. This call takes a `glib::Variant`. The +correct type for the state is determined by a static state type +(which is given at construction time). + +The state may have a hint associated with it, specifying its valid +range. + +`Action` is merely the interface to the concept of an action, as +described above. Various implementations of actions exist, including +`SimpleAction`. + +In all cases, the implementing class is responsible for storing the +name of the action, the parameter type, the enabled state, the +optional state type and the state and emitting the appropriate +signals when these change. The implementor is responsible for filtering +calls to `Action::activate` and `Action::change_state` for type +safety and for the state being enabled. + +Probably the only useful thing to do with a `Action` is to put it +inside of a `SimpleActionGroup`. + +# Implements + +[`ActionExt`](trait.ActionExt.html) + +Trait containing all `Action` methods. + +# Implementors + +[`Action`](struct.Action.html), [`SimpleAction`](struct.SimpleAction.html) + +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 `None`. + +Feature: `v2_38` + +## `action_name` +an potential action name + +# Returns + +`true` if `action_name` is valid + +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 `glib::Variant::parse`. If a tuple-typed +value is desired, it must be specified in the same way, resulting in +two sets of parens, for example: "app.action((1,2,3))". A string +target can be specified this way as well: "app.action('target')". +For strings, this third format must be used if * target value is +empty or contains characters other than alphanumerics, '-' and '.'. + +Feature: `v2_38` + +## `detailed_name` +a detailed action name +## `action_name` +the action name +## `target_value` +the target value, or `None` for no target + +# Returns + +`true` if successful, else `false` with `error` set + +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 `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. + +Feature: `v2_38` + +## `action_name` +a valid action name +## `target_value` +a `glib::Variant` target value, or `None` + +# Returns + +a detailed format string + +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 `None` then `parameter` must also be `None`. + +If the `parameter` GVariant is floating, it is consumed. +## `parameter` +the parameter to the activation + +Request for the state of `self` to be changed to `value`. + +The action must be stateful and `value` must be of the correct type. +See `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 `Action::get_state_hint`. + +If the `value` GVariant is floating, it is consumed. +## `value` +the new state + +Checks if `self` is currently enabled. + +An action must be enabled in order to be activated or in order to +have its state changed from outside callers. + +# Returns + +whether the action is enabled + +Queries the name of `self`. + +# Returns + +the name of the action + +Queries the type of the parameter that must be given when activating +`self`. + +When activating the action using `Action::activate`, the `glib::Variant` +given to that function must be of the type returned by this function. + +In the case that this function returns `None`, you must not give any +`glib::Variant`, but `None` instead. + +# Returns + +the parameter type + +Queries the current state of `self`. + +If the action is not stateful then `None` will be returned. If the +action is stateful then the type of the return value is the type +given by `Action::get_state_type`. + +The return value (if non-`None`) should be freed with +`glib::Variant::unref` when it is no longer required. + +# Returns + +the current state of the action + +Requests a hint about the valid range of values for the state of +`self`. + +If `None` 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 `glib::Variant` array is returned then each item in the array is a +possible value for the state. If a `glib::Variant` pair (ie: two-tuple) is +returned then the tuple specifies the inclusive lower and upper bound +of valid values for the state. + +In any case, the information is merely a hint. It may be possible to +have a state value outside of the hinted range and setting a value +within the range may fail. + +The return value (if non-`None`) should be freed with +`glib::Variant::unref` when it is no longer required. + +# Returns + +the state range hint + +Queries the type of the state of `self`. + +If the action is stateful (e.g. created with +`SimpleAction::new_stateful`) then this function returns the +`glib::VariantType` of the state. This is the type of the initial value +given as the state. All calls to `Action::change_state` must give a +`glib::Variant` of this type and `Action::get_state` will return a +`glib::Variant` of the same type. + +If the action is not stateful (e.g. created with `SimpleAction::new`) +then this function will return `None`. In that case, `Action::get_state` +will return `None` and you must not call `Action::change_state`. + +# Returns + +the state type, if the action is stateful + +`ActionGroup` 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 `MenuModel` that provides additional +representation data for displaying the actions to the user, e.g. in +a menu. + +The main way to interact with the actions in a GActionGroup is to +activate them with `ActionGroup::activate_action`. Activating an +action may require a `glib::Variant` parameter. The required type of the +parameter can be inquired with `ActionGroup::get_action_parameter_type`. +Actions may be disabled, see `ActionGroup::get_action_enabled`. +Activating a disabled action has no effect. + +Actions may optionally have a state in the form of a `glib::Variant`. The +current state of an action can be inquired with +`ActionGroup::get_action_state`. Activating a stateful action may +change its state, but it is also possible to set the state by calling +`ActionGroup::change_action_state`. + +As typical example, consider a text editing application which has an +option to change the current font to 'bold'. A good way to represent +this would be a stateful action, with a boolean state. Activating the +action would toggle the state. + +Each action in the group has a unique name (which is a string). All +method calls, except `ActionGroup::list_actions` take the name of +an action as an argument. + +The `ActionGroup` 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 - `ActionGroup::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 `ActionGroup` should provide implementations for +the virtual functions `ActionGroup::list_actions` and +`ActionGroup::query_action`. The other virtual functions should +not be implemented - their "wrappers" are actually implemented with +calls to `ActionGroup::query_action`. + +# Implements + +[`ActionGroupExt`](trait.ActionGroupExt.html) + +Trait containing all `ActionGroup` methods. + +# Implementors + +[`ActionGroup`](struct.ActionGroup.html), [`Application`](struct.Application.html), [`SimpleActionGroup`](struct.SimpleActionGroup.html) + +Emits the `ActionGroup::action-added` signal on `self`. + +This function should only be called by `ActionGroup` implementations. +## `action_name` +the name of an action in the group + +Emits the `ActionGroup::action-enabled-changed` signal on `self`. + +This function should only be called by `ActionGroup` implementations. +## `action_name` +the name of an action in the group +## `enabled` +whether or not the action is now enabled + +Emits the `ActionGroup::action-removed` signal on `self`. + +This function should only be called by `ActionGroup` implementations. +## `action_name` +the name of an action in the group + +Emits the `ActionGroup::action-state-changed` signal on `self`. + +This function should only be called by `ActionGroup` implementations. +## `action_name` +the name of an action in the group +## `state` +the new state of the named action + +Activate the named action within `self`. + +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 `None`. See +`ActionGroup::get_action_parameter_type`. +## `action_name` +the name of the action to activate +## `parameter` +parameters to the activation + +Request for the state of the named action within `self` to be +changed to `value`. + +The action must be stateful and `value` must be of the correct type. +See `ActionGroup::get_action_state_type`. + +This call merely requests a change. The action may refuse to change +its state or may change its state to something other than `value`. +See `ActionGroup::get_action_state_hint`. + +If the `value` GVariant is floating, it is consumed. +## `action_name` +the name of the action to request the change on +## `value` +the new state + +Checks if the named action within `self` is currently enabled. + +An action must be enabled in order to be activated or in order to +have its state changed from outside callers. +## `action_name` +the name of the action to query + +# Returns + +whether or not the action is currently enabled + +Queries the type of the parameter that must be given when activating +the named action within `self`. + +When activating the action using `ActionGroup::activate_action`, +the `glib::Variant` given to that function must be of the type returned +by this function. + +In the case that this function returns `None`, you must not give any +`glib::Variant`, but `None` 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. +## `action_name` +the name of the action to query + +# Returns + +the parameter type + +Queries the current state of the named action within `self`. + +If the action is not stateful then `None` will be returned. If the +action is stateful then the type of the return value is the type +given by `ActionGroup::get_action_state_type`. + +The return value (if non-`None`) should be freed with +`glib::Variant::unref` when it is no longer required. +## `action_name` +the name of the action to query + +# Returns + +the current state of the action + +Requests a hint about the valid range of values for the state of the +named action within `self`. + +If `None` 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 `glib::Variant` array is returned then each item in the array is a +possible value for the state. If a `glib::Variant` pair (ie: two-tuple) is +returned then the tuple specifies the inclusive lower and upper bound +of valid values for the state. + +In any case, the information is merely a hint. It may be possible to +have a state value outside of the hinted range and setting a value +within the range may fail. + +The return value (if non-`None`) should be freed with +`glib::Variant::unref` when it is no longer required. +## `action_name` +the name of the action to query + +# Returns + +the state range hint + +Queries the type of the state of the named action within +`self`. + +If the action is stateful then this function returns the +`glib::VariantType` of the state. All calls to +`ActionGroup::change_action_state` must give a `glib::Variant` of this +type and `ActionGroup::get_action_state` will return a `glib::Variant` +of the same type. + +If the action is not stateful then this function will return `None`. +In that case, `ActionGroup::get_action_state` will return `None` +and you must not call `ActionGroup::change_action_state`. + +The state type of a particular action will never change but it is +possible for an action to be removed and for a new action to be added +with the same name but a different state type. +## `action_name` +the name of the action to query + +# Returns + +the state type, if the action is stateful + +Checks if the named action exists within `self`. +## `action_name` +the name of the action to check for + +# Returns + +whether the named action exists + +Lists the actions contained within `self`. + +The caller is responsible for freeing the list with `g_strfreev` when +it is no longer required. + +# Returns + +a `None`-terminated array of the names of the +actions in the group + +Queries all aspects of the named action within an `self`. + +This function acquires the information available from +`ActionGroup::has_action`, `ActionGroup::get_action_enabled`, +`ActionGroup::get_action_parameter_type`, +`ActionGroup::get_action_state_type`, +`ActionGroup::get_action_state_hint` and +`ActionGroup::get_action_state` with a single function call. + +This provides two main benefits. + +The first is the improvement in efficiency that comes with not having +to perform repeated lookups of the action in order to discover +different things about it. The second is that implementing +`ActionGroup` can now be done by only overriding this one virtual +function. + +The interface provides a default implementation of this function that +calls the individual functions, as required, to fetch the +information. The interface also provides default implementations of +those functions that call this function. All implementations, +therefore, must override either this function or all of the others. + +If the action exists, `true` is returned and any of the requested +fields (as indicated by having a non-`None` reference passed in) are +filled. If the action doesn't exist, `false` is returned and the +fields may or may not have been modified. +## `action_name` +the name of an action in the group +## `enabled` +if the action is presently enabled +## `parameter_type` +the parameter type, or `None` if none needed +## `state_type` +the state type, or `None` if stateless +## `state_hint` +the state hint, or `None` if none +## `state` +the current state, or `None` if stateless + +# Returns + +`true` if the action exists, else `false` + +The GActionMap interface is implemented by `ActionGroup` +implementations that operate by containing a number of +named `Action` instances, such as `SimpleActionGroup`. + +One useful application of this interface is to map the +names of actions from various action groups to unique, +prefixed names (e.g. by prepending "app." or "win."). +This is the motivation for the 'Map' part of the interface +name. + +# Implements + +[`ActionMapExt`](trait.ActionMapExt.html) + +Trait containing all `ActionMap` methods. + +# Implementors + +[`ActionMap`](struct.ActionMap.html), [`Application`](struct.Application.html), [`SimpleActionGroup`](struct.SimpleActionGroup.html) + +Adds an action to the `self`. + +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`. +## `action` +a `Action` + +A convenience function for creating multiple `SimpleAction` instances +and adding them to a `ActionMap`. + +Each action is constructed as per one `ActionEntry`. + + +```C +static void +activate_quit (GSimpleAction *simple, + GVariant *parameter, + gpointer user_data) +{ + exit (0); +} + +static void +activate_print_string (GSimpleAction *simple, + GVariant *parameter, + gpointer user_data) +{ + g_print ("%s\n", g_variant_get_string (parameter, NULL)); +} + +static GActionGroup * +create_action_group (void) +{ + const GActionEntry entries[] = { + { "quit", activate_quit }, + { "print-string", activate_print_string, "s" } + }; + GSimpleActionGroup *group; + + group = g_simple_action_group_new (); + g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); + + return G_ACTION_GROUP (group); +} +``` +## `entries` +a pointer to + the first item in an array of `ActionEntry` structs +## `n_entries` +the length of `entries`, or -1 if `entries` is `None`-terminated +## `user_data` +the user data for signal connections + +Looks up the action with the name `action_name` in `self`. + +If no such action exists, returns `None`. +## `action_name` +the name of an action + +# Returns + +a `Action`, or `None` + +Removes the named action from the action map. + +If no action of this name is in the map then nothing happens. +## `action_name` +the name of the action + +`AppInfo` and `AppLaunchContext` 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 `File::get_path`) when using `AppInfo::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 `File` constructors (since gvfs +implements the `Vfs` extension point). As such, if the application +needs to examine the URI, it needs to use `File::get_uri` or +similar on `File`. In other words, an application cannot assume +that the URI passed to e.g. `File::new_for_commandline_arg` is +equal to the result of `File::get_uri`. The following snippet +illustrates this: + + +```text +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. + +# Implements + +[`AppInfoExt`](trait.AppInfoExt.html) + +Trait containing all `AppInfo` methods. + +# Implementors + +[`AppInfo`](struct.AppInfo.html) + +Creates a new `AppInfo` from the given information. + +Note that for `commandline`, the quoting rules of the Exec key of the +[freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) +are applied. For example, if the `commandline` contains +percent-encoded URIs, the percent-character must be doubled in order to prevent it from +being swallowed by Exec key unquoting. See the specification for exact quoting rules. +## `commandline` +the commandline to use +## `application_name` +the application name, or `None` to use `commandline` +## `flags` +flags that can specify details of the created `AppInfo` + +# Returns + +new `AppInfo` for given command. + +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 `AppInfo::should_show`. +The returned list does not include applications which have +the `Hidden` key set. + +# Returns + +a newly allocated `glib::List` of references to `GAppInfos`. + +Gets a list of all `GAppInfos` for a given content type, +including the recommended and fallback `GAppInfos`. See +`AppInfo::get_recommended_for_type` and +`AppInfo::get_fallback_for_type`. +## `content_type` +the content type to find a `AppInfo` for + +# Returns + +`glib::List` of `GAppInfos` + for given `content_type` or `None` on error. + +Gets the default `AppInfo` for a given content type. +## `content_type` +the content type to find a `AppInfo` for +## `must_support_uris` +if `true`, the `AppInfo` is expected to + support URIs + +# Returns + +`AppInfo` for given `content_type` or + `None` on error. + +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". +## `uri_scheme` +a string containing a URI scheme. + +# Returns + +`AppInfo` for given `uri_scheme` or `None` on error. + +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. +## `content_type` +the content type to find a `AppInfo` for + +# Returns + +`glib::List` of `GAppInfos` + for given `content_type` or `None` on error. + +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 `AppInfo::set_as_last_used_for_type` has been +called. +## `content_type` +the content type to find a `AppInfo` for + +# Returns + +`glib::List` of `GAppInfos` + for given `content_type` or `None` on error. + +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. +## `uri` +the uri to show +## `launch_context` +an optional `AppLaunchContext` + +# Returns + +`true` on success, `false` on error. + +Async version of `AppInfo::launch_default_for_uri`. + +This version is useful if you are interested in receiving +error information in the case where the application is +sandboxed and the portal may present an application chooser +dialog to the user. + +Feature: `v2_50` + +## `uri` +the uri to show +## `callback` +a `GASyncReadyCallback` to call when the request is done +## `user_data` +data to pass to `callback` + +Finishes an asynchronous launch-default-for-uri operation. + +Feature: `v2_50` + +## `result` +a `AsyncResult` + +# Returns + +`true` if the launch was successful, `false` if `error` is set + +Removes all changes to the type associations done by +`AppInfo::set_as_default_for_type`, +`AppInfo::set_as_default_for_extension`, +`AppInfo::add_supports_type` or +`AppInfo::remove_supports_type`. +## `content_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. +## `content_type` +a string. + +# Returns + +`true` on success, `false` on error. + +Obtains the information whether the `AppInfo` can be deleted. +See `AppInfo::delete`. + +# Returns + +`true` if `self` can be deleted + +Checks if a supported content type can be removed from an application. + +# Returns + +`true` if it is possible to remove supported + content types from a given `self`, `false` if not. + +Tries to delete a `AppInfo`. + +On some platforms, there may be a difference between user-defined +`GAppInfos` which can be deleted, and system-wide ones which cannot. +See `AppInfo::can_delete`. + +# Returns + +`true` if `self` has been deleted + +Creates a duplicate of a `AppInfo`. + +# Returns + +a duplicate of `self`. + +Checks if two `GAppInfos` are equal. +## `appinfo2` +the second `AppInfo`. + +# Returns + +`true` if `self` is equal to `appinfo2`. `false` otherwise. + +Gets the commandline with which the application will be +started. + +# Returns + +a string containing the `self`'s commandline, + or `None` if this information is not available + +Gets a human-readable description of an installed application. + +# Returns + +a string containing a description of the +application `self`, or `None` if none. + +Gets the display name of the application. The display name is often more +descriptive to the user than the name itself. + +# Returns + +the display name of the application for `self`, or the name if +no display name is available. + +Gets the executable's name for the installed application. + +# Returns + +a string containing the `self`'s application +binaries name + +Gets the icon for the application. + +# Returns + +the default `Icon` for `self` or `None` +if there is no default icon. + +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 `None`, depending on how +the `self` has been constructed. + +# Returns + +a string containing the application's ID. + +Gets the installed name of the application. + +# Returns + +the name of the application for `self`. + +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 `None`. +This function does not take in consideration associations added with +`AppInfo::add_supports_type`, but only those exported directly by +the application. + +Feature: `v2_34` + + +# Returns + + + a list of content types. + +Launches the application. Passes `files` to the launched application +as arguments, using the optional `launch_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 `None` `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 +`AppInfo::launch_uris` instead. + +The launched application inherits the environment of the launching +process, but it can be modified with `AppLaunchContextExt::setenv` +and `AppLaunchContextExt::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 `launch_context`. +## `files` +a `glib::List` of `File` objects +## `launch_context` +a `AppLaunchContext` or `None` + +# Returns + +`true` on successful launch, `false` otherwise. + +Launches the application. This passes the `uris` to the launched application +as arguments, using the optional `launch_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 `None` `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. +## `uris` +a `glib::List` containing URIs to launch. +## `launch_context` +a `AppLaunchContext` or `None` + +# Returns + +`true` on successful launch, `false` otherwise. + +Removes a supported type from an application, if possible. +## `content_type` +a string. + +# Returns + +`true` on success, `false` on error. + +Sets the application as the default handler for the given file extension. +## `extension` +a string containing the file extension + (without the dot). + +# Returns + +`true` on success, `false` on error. + +Sets the application as the default handler for a given type. +## `content_type` +the content type. + +# Returns + +`true` on success, `false` on error. + +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 `AppInfo::get_recommended_for_type`, regardless of the default +application for that content type. +## `content_type` +the content type. + +# Returns + +`true` on success, `false` on error. + +Checks if the application info should be shown in menus that +list available applications. + +# Returns + +`true` if the `self` should be shown, `false` otherwise. + +Checks if the application accepts files as arguments. + +# Returns + +`true` if the `self` supports files. + +Checks if the application supports reading files and directories from URIs. + +# Returns + +`true` if the `self` supports URIs. + +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. + +# Implements + +[`AppLaunchContextExt`](trait.AppLaunchContextExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `AppLaunchContext` methods. + +# Implementors + +[`AppLaunchContext`](struct.AppLaunchContext.html) + +Creates a new application launch context. This is not normally used, +instead you instantiate a subclass of this, such as ``GdkAppLaunchContext``. + +# Returns + +a `AppLaunchContext`. + +Gets the display string for the `self`. This is used to ensure new +applications are started on the same display as the launching +application, by setting the `DISPLAY` environment variable. +## `info` +a `AppInfo` +## `files` +a `glib::List` of `File` objects + +# Returns + +a display string for the display. + +Gets the complete environment variable list to be passed to +the child process when `self` is used to launch an application. +This is a `None`-terminated array of strings, where each string has +the form `KEY=VALUE`. + +# Returns + +the + child's environment + +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"). +## `info` +a `AppInfo` +## `files` +a `glib::List` of of `File` objects + +# Returns + +a startup notification ID for the application, or `None` if + not supported. + +Called when an application has failed to launch, so that it can cancel +the application startup notification started in `AppLaunchContextExt::get_startup_notify_id`. +## `startup_notify_id` +the startup notification id that was returned by `AppLaunchContextExt::get_startup_notify_id`. + +Arranges for `variable` to be set to `value` in the child's +environment when `self` is used to launch an application. +## `variable` +the environment variable to set +## `value` +the value for to set the variable to. + +Arranges for `variable` to be unset in the child's environment +when `self` is used to launch an application. +## `variable` +the environment variable to remove + +A `Application` 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 `ApplicationExt::hold` and `ApplicationExt::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 `Application` 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 +`Application` should do very little more than instantiating the +application instance, possibly connecting signal handlers, then +calling `ApplicationExt::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 `ApplicationExt::run` promptly returns. See the code +examples below. + +If used, the expected form of an application identifier is very close +to that of of a +[DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html`message`-protocol-names-interface). +Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator". +For details on valid application identifiers, see `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 `Application` +attempts to acquire the bus name of your application (which happens in +`ApplicationExt::register`). Unfortunately, this means that you cannot use +`ApplicationExt::get_is_remote` to decide if you want to register object paths. + +GApplication also implements the `ActionGroup` and `ActionMap` +interfaces and lets you easily export actions by adding them with +`ActionMap::add_action`. When invoking an action by calling +`ActionGroup::activate_action` on the application, it is always +invoked in the primary instance. The actions are also exported on +the session bus, and GIO provides the `DBusActionGroup` wrapper to +conveniently access them remotely. GIO provides a `DBusMenuModel` 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 `Application::startup` signal lets you handle the application +initialization for all of these in a single place. + +Regardless of which of these entry points is used to start the +application, GApplication passes some "platform data from the +launching instance to the primary instance, in the form of a +`glib::Variant` dictionary mapping strings to variants. To use platform +data, override the `before_emit` or `after_emit` virtual functions +in your `Application` subclass. When dealing with +`ApplicationCommandLine` objects, the platform data is +directly available via `ApplicationCommandLine::get_cwd`, +`ApplicationCommandLine::get_environ` and +`ApplicationCommandLine::get_platform_data`. + +As the name indicates, the platform data may vary depending on the +operating system, but it always includes the current directory (key +"cwd"), and optionally the environment (ie the set of environment +variables and their values) of the calling process (key "environ"). +The environment is only added to the platform data if the +`ApplicationFlags::SendEnvironment` flag is set. `Application` 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 +`Application::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). + +# Implements + +[`ApplicationExt`](trait.ApplicationExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html), [`ActionMapExt`](trait.ActionMapExt.html) + +Trait containing all `Application` methods. + +# Implementors + +[`Application`](struct.Application.html) + +Creates a new `Application` instance. + +If non-`None`, the application id must be valid. See +`Application::id_is_valid`. + +If no application ID is given then some features of `Application` +(most notably application uniqueness) will be disabled. +## `application_id` +the application id +## `flags` +the application flags + +# Returns + +a new `Application` instance + +Returns the default `Application` instance for this process. + +Normally there is only one `Application` per process and it becomes +the default when it is created. You can exercise more control over +this by using `ApplicationExt::set_default`. + +If there is no default application then `None` is returned. + +# Returns + +the default application for this process, or `None` + +Checks if `application_id` is a valid application identifier. + +A valid ID is required for calls to `Application::new` and +`ApplicationExt::set_application_id`. + +For convenience, the restrictions on application identifiers are +reproduced here: + +- Application identifiers must contain only the ASCII characters + "[A-Z][a-z][0-9]_-." and must not begin with a digit. + +- Application identifiers must contain at least one '.' (period) + character (and thus at least three elements). + +- Application identifiers must not begin or end with a '.' (period) + character. + +- Application identifiers must not contain consecutive '.' (period) + characters. + +- Application identifiers must not exceed 255 characters. +## `application_id` +a potential application identifier + +# Returns + +`true` if `application_id` is valid + +Activates the application. + +In essence, this results in the `Application::activate` signal being +emitted in the primary instance. + +The application must be registered before calling this function. + +Add an option to be handled by `self`. + +Calling this function is the equivalent of calling +`ApplicationExt::add_main_option_entries` with a single `glib::OptionEntry` +that has its arg_data member set to `None`. + +The parsed arguments will be packed into a `glib::VariantDict` which +is passed to `Application::handle-local-options`. If +`ApplicationFlags::HandlesCommandLine` is set, then it will also +be sent to the primary instance. See +`ApplicationExt::add_main_option_entries` for more details. + +See `glib::OptionEntry` for more documentation of the arguments. + +Feature: `v2_42` + +## `long_name` +the long name of an option used to specify it in a commandline +## `short_name` +the short name of an option +## `flags` +flags from `glib::OptionFlags` +## `arg` +the type of the option, as a `glib::OptionArg` +## `description` +the description for the option in `--help` output +## `arg_description` +the placeholder to use for the extra argument + parsed by the option in `--help` output + +Adds main option entries to be handled by `self`. + +This function is comparable to `glib::OptionContext::add_main_entries`. + +After the commandline arguments are parsed, the +`Application::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 `glib::OptionContext`, `Application` supports giving a `None` +`arg_data` for a non-callback `glib::OptionEntry`. This results in the +argument in question being packed into a `glib::VariantDict` which is also +passed to `Application::handle-local-options`, where it can be +inspected and modified. If `ApplicationFlags::HandlesCommandLine` is +set, then the resulting dictionary is sent to the primary instance, +where `ApplicationCommandLine::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" `glib::Variant` 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 +`glib::VariantDict::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. `Application` 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 +`ApplicationFlags::HandlesCommandLine` is unset. + +If `Application::handle-local-options` needs to see the list of +filenames, then the use of `G_OPTION_REMAINING` is recommended. If +`arg_data` is `None` 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 `glib::VariantDict::lookup`: +- for `glib::OptionArg::None`, use b +- for `glib::OptionArg::String`, use &s +- for `glib::OptionArg::Int`, use i +- for `glib::OptionArg::Int64`, use x +- for `glib::OptionArg::Double`, use d +- for `glib::OptionArg::Filename`, use ^ay +- for `glib::OptionArg::StringArray`, use &as +- for `glib::OptionArg::FilenameArray`, use ^aay + +Feature: `v2_40` + +## `entries` +a + `None`-terminated list of `GOptionEntrys` + +Adds a `glib::OptionGroup` to the commandline handling of `self`. + +This function is comparable to `glib::OptionContext::add_group`. + +Unlike `ApplicationExt::add_main_option_entries`, this function does +not deal with `None` `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 `Application::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 `glib::OptionGroup` 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 +`ApplicationFlags::HandlesCommandLine` was given. + +Feature: `v2_40` + +## `group` +a `glib::OptionGroup` + +Marks `self` as busy (see `ApplicationExt::mark_busy`) while +`property` on `object` is `true`. + +The binding holds a reference to `self` while it is active, but +not to `object`. Instead, the binding is destroyed when `object` is +finalized. + +Feature: `v2_44` + +## `object` +a `gobject::Object` +## `property` +the name of a boolean property of `object` + +Gets the unique identifier for `self`. + +# Returns + +the identifier for `self`, owned by `self` + +Gets the `DBusConnection` being used by the application, or `None`. + +If `Application` is using its D-Bus backend then this function will +return the `DBusConnection` being used for uniqueness and +communication with the desktop environment and other instances of the +application. + +If `Application` is not using D-Bus then this function will return +`None`. 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 `ApplicationExt::get_is_registered`. + +Feature: `v2_34` + + +# Returns + +a `DBusConnection`, or `None` + +Gets the D-Bus object path being used by the application, or `None`. + +If `Application` is using its D-Bus backend then this function will +return the D-Bus object path that `Application` 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 `Application` is not using D-Bus then this function will return +`None`. 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 `ApplicationExt::get_is_registered`. + +Feature: `v2_34` + + +# Returns + +the object path, or `None` + +Gets the flags for `self`. + +See `ApplicationFlags`. + +# Returns + +the flags for `self` + +Gets the current inactivity timeout for the application. + +This is the amount of time (in milliseconds) after the last call to +`ApplicationExt::release` before the application stops running. + +# Returns + +the timeout, in milliseconds + +Gets the application's current busy state, as set through +`ApplicationExt::mark_busy` or `ApplicationExt::bind_busy_property`. + +Feature: `v2_44` + + +# Returns + +`true` if `self` is currenty marked as busy + +Checks if `self` is registered. + +An application is registered if `ApplicationExt::register` has been +successfully called. + +# Returns + +`true` if `self` is registered + +Checks if `self` is remote. + +If `self` is remote then it means that another instance of +application already exists (the 'primary' instance). Calls to +perform actions on `self` will result in the actions being +performed by the primary instance. + +The value of this property cannot be accessed before +`ApplicationExt::register` has been called. See +`ApplicationExt::get_is_registered`. + +# Returns + +`true` if `self` is remote + +Gets the resource base path of `self`. + +See `ApplicationExt::set_resource_base_path` for more information. + +Feature: `v2_42` + + +# Returns + +the base resource path, if one is set + +Increases the use count of `self`. + +Use this function to indicate that the application has a reason to +continue to run. For example, `ApplicationExt::hold` is called by GTK+ +when a toplevel window is on the screen. + +To cancel the hold, call `ApplicationExt::release`. + +Increases the busy count of `self`. + +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 `ApplicationExt::unmark_busy`. + +Feature: `v2_38` + + +Opens the given files. + +In essence, this results in the `Application::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 `ApplicationFlags::HandlesOpen` flag set. +## `files` +an array of `GFiles` to open +## `n_files` +the length of the `files` array +## `hint` +a hint (or ""), but never `None` + +Immediately quits the application. + +Upon return to the mainloop, `ApplicationExt::run` will return, +calling only the 'shutdown' function before doing so. + +The hold count is ignored. + +The result of calling `ApplicationExt::run` again after it returns is +unspecified. + +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 `ApplicationFlags::NonUnique` 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 `Application::startup` signal is emitted if registration succeeds +and `self` 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 +`ApplicationExt::get_is_remote` for that. +## `cancellable` +a `Cancellable`, or `None` + +# Returns + +`true` if registration succeeded + +Decrease the use count of `self`. + +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 `ApplicationExt::hold`. + +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 `None` 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). + +`Application` will attempt to parse the commandline arguments. You +can add commandline flags to the list of recognised options by way of +`ApplicationExt::add_main_option_entries`. After this, the +`Application::handle-local-options` signal is emitted, from which the +application can inspect the values of its `GOptionEntrys`. + +`Application::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 `Application::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 +`ApplicationFlags::HandlesCommandLine` was specified then the remaining +commandline arguments are sent to the primary instance, where a +`Application::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 +`Application::activate` signal. If there are one or more files, and +`ApplicationFlags::HandlesOpen` was specified then the files are opened +via the `Application::open` signal. + +If you are interested in doing more complicated local handling of the +commandline then you should implement your own `Application` 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 `ApplicationFlags::IsService` 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 `ApplicationExt::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 `glib::MainLoop::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 `ApplicationFlags::IsService` or +`ApplicationFlags::IsLauncher` 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 +`ApplicationFlags::IsService` 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. +## `argc` +the argc from `main` (or 0 if `argv` is `None`) +## `argv` +the argv from `main`, or `None` + +# Returns + +the exit status + +Sends a notification on behalf of `self` 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 `None`, but it is impossible to replace or withdraw +notifications without an id. + +If `notification` is no longer relevant, it can be withdrawn with +`ApplicationExt::withdraw_notification`. + +Feature: `v2_40` + +## `id` +id of the notification, or `None` +## `notification` +the `Notification` to send + +This used to be how actions were associated with a `Application`. +Now there is `ActionMap` for that. + +# Deprecated since 2.32 + +Use the `ActionMap` interface instead. Never ever +mix use of this API with use of `ActionMap` on the same `self` +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 `ActionMap` instead. +## `action_group` +a `ActionGroup`, or `None` + +Sets the unique identifier for `self`. + +The application id can only be modified if `self` has not yet +been registered. + +If non-`None`, the application id must be valid. See +`Application::id_is_valid`. +## `application_id` +the identifier for `self` + +Sets or unsets the default application for the process, as returned +by `Application::get_default`. + +This function does not take its own reference on `self`. If +`self` is destroyed then the default application will revert +back to `None`. + +Sets the flags for `self`. + +The flags can only be modified if `self` has not yet been +registered. + +See `ApplicationFlags`. +## `flags` +the flags for `self` + +Sets the current inactivity timeout for the application. + +This is the amount of time (in milliseconds) after the last call to +`ApplicationExt::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 `ApplicationExt::release` drops the use count to +zero. Any timeouts currently in progress are not impacted. +## `inactivity_timeout` +the timeout, in milliseconds + +Sets (or unsets) the base resource path of `self`. + +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 `Application` 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 `Resource` for more information about adding resources to your +application. + +You can disable automatic resource loading functionality by setting +the path to `None`. + +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 `Application` you should either set the +`Application:resource-base-path` property at construction time, or call +this function during the instance initialization. Alternatively, you +can call this function in the `ApplicationClass.startup` virtual function, +before chaining up to the parent implementation. + +Feature: `v2_42` + +## `resource_path` +the resource path to use + +Destroys a binding between `property` and the busy state of +`self` that was previously created with +`ApplicationExt::bind_busy_property`. + +Feature: `v2_44` + +## `object` +a `gobject::Object` +## `property` +the name of a boolean property of `object` + +Decreases the busy count of `self`. + +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 `ApplicationExt::mark_busy`. + +Feature: `v2_38` + + +Withdraws a notification that was sent with +`ApplicationExt::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. + +Feature: `v2_40` + +## `id` +id of a previously sent notification + +GCancellable is a thread-safe operation cancellation stack used +throughout GIO to allow for cancellation of synchronous and +asynchronous operations. + +# Implements + +[`CancellableExt`](trait.CancellableExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Cancellable` methods. + +# Implementors + +[`Cancellable`](struct.Cancellable.html) + +Creates a new `Cancellable` object. + +Applications that want to start one or more operations +that should be cancellable should create a `Cancellable` +and pass it to the operations. + +One `Cancellable` can be used in multiple consecutive +operations or in multiple concurrent operations. + +# Returns + +a `Cancellable`. + +Gets the top cancellable from the stack. + +# Returns + +a `Cancellable` from the top +of the stack, or `None` if the stack is empty. + +Will set `self` to cancelled, and will emit the +`Cancellable::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 `self`. + +If `self` is `None`, 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. + +Convenience function to connect to the `Cancellable::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 `self` is already cancelled, +or when `self` 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 `Cancellable::cancelled` for details on how to use this. + +Since GLib 2.40, the lock protecting `self` 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. `CancellableExt::cancel`. +## `callback` +The `GCallback` to connect. +## `data` +Data to pass to `callback`. +## `data_destroy_func` +Free function for `data` or `None`. + +# Returns + +The id of the signal handler or 0 if `self` has already + been cancelled. + +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 +`Cancellable::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 `Cancellable::cancelled` for +details on how to use this. + +If `self` is `None` or `handler_id` is `0` this function does +nothing. +## `handler_id` +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 `self` 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 `CancellableExt::reset`. + +After a successful return from this function, you should use +`CancellableExt::release_fd` to free up resources allocated for +the returned file descriptor. + +See also `CancellableExt::make_pollfd`. + +# Returns + +A valid file descriptor. %-1 if the file descriptor +is not supported, or on errors. + +Checks if a cancellable job has been cancelled. + +# Returns + +`true` if `self` is cancelled, +FALSE if called with `None` or if item is not cancelled. + +Creates a `glib::PollFD` corresponding to `self`; 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 +`CancellableExt::release_fd` to free up resources allocated for the +`pollfd`. After a `false` return, do not call `CancellableExt::release_fd`. + +If this function returns `false`, either no `self` 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 `self`. + +You are not supposed to read from the fd yourself, just check for +readable status. Reading to unset the readable status is done +with `CancellableExt::reset`. +## `pollfd` +a pointer to a `glib::PollFD` + +# Returns + +`true` if `pollfd` was successfully initialized, `false` on + failure to prepare the cancellable. + +Pops `self` off the cancellable stack (verifying that `self` +is on the top of the stack). + +Pushes `self` onto the cancellable stack. The current +cancellable can then be received using `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. `File` operations, +so you rarely have to call this yourself. + +Releases a resources previously allocated by `CancellableExt::get_fd` +or `CancellableExt::make_pollfd`. + +For compatibility reasons with older releases, calling this function +is not strictly required, the resources will be automatically freed +when the `self` is finalized. However, the `self` 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. + +Resets `self` 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. + +If the `self` is cancelled, sets the error to notify +that the operation was cancelled. + +# Returns + +`true` if `self` was cancelled, `false` if it was not + +Creates a source that triggers if `self` is cancelled and +calls its callback of type `GCancellableSourceFunc`. This is +primarily useful for attaching to another (non-cancellable) source +with `glib::Source::add_child_source` to add cancellability to it. + +For convenience, you can call this with a `None` `Cancellable`, +in which case the source will never trigger. + +The new `glib::Source` will hold a reference to the `Cancellable`. + +# Returns + +the new `glib::Source`. + +`File` 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 +`File` objects do not represent files, merely an identifier for a +file. All file content I/O is implemented as streaming operations +(see `InputStream` and `OutputStream`). + +To construct a `File`, you can use: +- `File::new_for_path` if you have a path. +- `File::new_for_uri` if you have a URI. +- `File::new_for_commandline_arg` for a command line argument. +- `File::new_tmp` to create a temporary file from a template. +- `File::parse_name` from a UTF-8 string gotten from `File::get_parse_name`. + +One way to think of a `File` 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 +`File` using `File::get_parent` to get an identifier for the parent +directory, `File::get_child` to get a child within a directory, +`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 `File::get_parent` on two different +files. + +All `GFiles` have a basename (get with `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 `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 `File` to use to actually +access the file, because there is no way to go from a display name to +the actual name. + +Using `File` 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 `File` 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 `File` 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 `File` operations almost always take a noticeable amount of time, and +so do not have synchronous analogs. Notable cases include: +- `File::mount_mountable` to mount a mountable file. +- `File::unmount_mountable_with_operation` to unmount a mountable file. +- `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. + +# Implements + +[`FileExt`](trait.FileExt.html) + +Trait containing all `File` methods. + +# Implementors + +[`File`](struct.File.html) + +Creates a `File` 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. `Application` also uses UTF-8 but +`ApplicationCommandLine::create_file_for_arg` may be more useful +for you there. It is also always possible to use this function with +`glib::OptionContext` arguments of type `glib::OptionArg::Filename`. +## `arg` +a command line string + +# Returns + +a new `File`. + Free the returned object with `gobject::ObjectExt::unref`. + +Creates a `File` with the given argument from the command line. + +This function is similar to `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 `ApplicationCommandLine::create_file_for_arg`. + +Feature: `v2_36` + +## `arg` +a command line string +## `cwd` +the current working directory of the commandline + +# Returns + +a new `File` + +Constructs a `File` for a given path. This operation never +fails, but the returned object might not support any I/O +operation if `path` is malformed. +## `path` +a string containing a relative or absolute path. + The string must be encoded in the glib filename encoding. + +# Returns + +a new `File` for the given `path`. + Free the returned object with `gobject::ObjectExt::unref`. + +Constructs a `File` 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. +## `uri` +a UTF-8 string containing a URI + +# Returns + +a new `File` for the given `uri`. + Free the returned object with `gobject::ObjectExt::unref`. + +Opens a file in the preferred directory for temporary files (as +returned by `g_get_tmp_dir`) and returns a `File` and +`FileIOStream` 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 `None`, a default template is used. + +Unlike the other `File` constructors, this will return `None` if +a temporary file could not be created. +## `tmpl` +Template for the file + name, as in `g_file_open_tmp`, or `None` for a default template +## `iostream` +on return, a `FileIOStream` for the created file + +# Returns + +a new `File`. + Free the returned object with `gobject::ObjectExt::unref`. + +Constructs a `File` with the given `parse_name` (i.e. something +given by `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. +## `parse_name` +a file name or path to be parsed + +# Returns + +a new `File`. + +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 `FileCreateFlags::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 `None`, then the operation can be cancelled +by triggering the cancellable object from another thread. If the +operation was cancelled, the error `IOErrorEnum::Cancelled` will be +returned. + +Some file systems don't allow all file names, and may return an +`IOErrorEnum::InvalidFilename` error. If the file is a directory the +`IOErrorEnum::IsDirectory` error will be returned. Other errors are +possible too, and depend on what kind of filesystem the file is on. +## `flags` +a set of `FileCreateFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileOutputStream`, or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously opens `self` for appending. + +For more details, see `File::append_to` which is +the synchronous version of this call. + +When the operation is finished, `callback` will be called. +You can then call `File::append_to_finish` to get the result +of the operation. +## `flags` +a set of `FileCreateFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous file append operation started with +`File::append_to_async`. +## `res` +`AsyncResult` + +# Returns + +a valid `FileOutputStream` + or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Copies the file `self` to the location specified by `destination`. +Can not handle recursive copies of directories. + +If the flag `FileCopyFlags::Overwrite` is specified an already +existing `destination` file is overwritten. + +If the flag `FileCopyFlags::NofollowSymlinks` is specified then symlinks +will be copied as symlinks, otherwise the target of the +`self` symlink will be copied. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +If `progress_callback` is not `None`, 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 `self` file does not exist, then the `IOErrorEnum::NotFound` error +is returned, independent on the status of the `destination`. + +If `FileCopyFlags::Overwrite` is not specified and the target exists, then +the error `IOErrorEnum::Exists` is returned. + +If trying to overwrite a file over a directory, the `IOErrorEnum::IsDirectory` +error is returned. If trying to overwrite a directory with a directory the +`IOErrorEnum::WouldMerge` error is returned. + +If the source is a directory and the target does not exist, or +`FileCopyFlags::Overwrite` is specified and the target is a file, then the +`IOErrorEnum::WouldRecurse` error is returned. + +If you are interested in copying the `File` object itself (not the on-disk +file), see `File::dup`. +## `destination` +destination `File` +## `flags` +set of `FileCopyFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `progress_callback` +function to callback with + progress information, or `None` if progress information is not needed +## `progress_callback_data` +user data to pass to `progress_callback` + +# Returns + +`true` on success, `false` otherwise. + +Copies the file `self` to the location specified by `destination` +asynchronously. For details of the behaviour, see `File::copy`. + +If `progress_callback` is not `None`, then that function that will be called +just like in `File::copy`. The callback will run in the default main context +of the thread calling `File::copy_async` — the same context as `callback` is +run in. + +When the operation is finished, `callback` will be called. You can then call +`File::copy_finish` to get the result of the operation. +## `destination` +destination `File` +## `flags` +set of `FileCopyFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `progress_callback` +function to callback with progress + information, or `None` if progress information is not needed +## `progress_callback_data` +user data to pass to `progress_callback` +## `callback` +a `GAsyncReadyCallback` to call when the request is satisfied +## `user_data` +the data to pass to callback function + +Copies the file attributes from `self` 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 `FileCopyFlags::AllMetadata` 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. +## `destination` +a `File` to copy attributes to +## `flags` +a set of `FileCopyFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the attributes were copied successfully, + `false` otherwise. + +Finishes copying the file started with `File::copy_async`. +## `res` +a `AsyncResult` + +# Returns + +a `true` on success, `false` on error. + +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 `FileCreateFlags::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 `None`, then the operation can be cancelled +by triggering the cancellable object from another thread. If the +operation was cancelled, the error `IOErrorEnum::Cancelled` will be +returned. + +If a file or directory with this name already exists the +`IOErrorEnum::Exists` error will be returned. Some file systems don't +allow all file names, and may return an `IOErrorEnum::InvalidFilename` +error, and if the name is to long `IOErrorEnum::FilenameTooLong` will +be returned. Other errors are possible too, and depend on what kind +of filesystem the file is on. +## `flags` +a set of `FileCreateFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileOutputStream` for the newly created + file, or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously creates a new file and returns an output stream +for writing to it. The file must not already exist. + +For more details, see `File::create` which is +the synchronous version of this call. + +When the operation is finished, `callback` will be called. +You can then call `File::create_finish` to get the result +of the operation. +## `flags` +a set of `FileCreateFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous file create operation started with +`File::create_async`. +## `res` +a `AsyncResult` + +# Returns + +a `FileOutputStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +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 `FileCreateFlags::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 `None`, then the operation can be cancelled +by triggering the cancellable object from another thread. If the +operation was cancelled, the error `IOErrorEnum::Cancelled` will be +returned. + +If a file or directory with this name already exists, the +`IOErrorEnum::Exists` error will be returned. Some file systems don't +allow all file names, and may return an `IOErrorEnum::InvalidFilename` +error, and if the name is too long, `IOErrorEnum::FilenameTooLong` +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. +## `flags` +a set of `FileCreateFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileIOStream` for the newly created + file, or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +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 `File::create_readwrite` which is +the synchronous version of this call. + +When the operation is finished, `callback` will be called. +You can then call `File::create_readwrite_finish` to get +the result of the operation. +## `flags` +a set of `FileCreateFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous file create operation started with +`File::create_readwrite_async`. +## `res` +a `AsyncResult` + +# Returns + +a `FileIOStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Deletes a file. If the `self` is a directory, it will only be +deleted if it is empty. This has the same semantics as `g_unlink`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the file was deleted. `false` otherwise. + +Asynchronously delete a file. If the `self` is a directory, it will +only be deleted if it is empty. This has the same semantics as +`g_unlink`. + +Feature: `v2_34` + +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes deleting a file started with `File::delete_async`. + +Feature: `v2_34` + +## `result` +a `AsyncResult` + +# Returns + +`true` if the file was deleted. `false` otherwise. + +Duplicates a `File` handle. This operation does not duplicate +the actual file or directory represented by the `File`; see +`File::copy` if attempting to copy a file. + +This call does no blocking I/O. + +# Returns + +a new `File` that is a duplicate + of the given `File`. + +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 +`File::eject_mountable_finish`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +# Deprecated since 2.22 + +Use `File::eject_mountable_with_operation` instead. +## `flags` +flags affecting the operation +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes an asynchronous eject operation started by +`File::eject_mountable`. + +# Deprecated since 2.22 + +Use `File::eject_mountable_with_operation_finish` + instead. +## `result` +a `AsyncResult` + +# Returns + +`true` if the `self` was ejected successfully. + `false` otherwise. + +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 +`File::eject_mountable_with_operation_finish`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `flags` +flags affecting the operation +## `mount_operation` +a `MountOperation`, + or `None` to avoid user interaction +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes an asynchronous eject operation started by +`File::eject_mountable_with_operation`. +## `result` +a `AsyncResult` + +# Returns + +`true` if the `self` was ejected successfully. + `false` otherwise. + +Gets the requested information about the files in a directory. +The result is a `FileEnumerator` object that will give out +`FileInfo` 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 `None`, then the operation can be cancelled +by triggering the cancellable object from another thread. If the +operation was cancelled, the error `IOErrorEnum::Cancelled` will be +returned. + +If the file does not exist, the `IOErrorEnum::NotFound` error will +be returned. If the file is not a directory, the `IOErrorEnum::NotDirectory` +error will be returned. Other errors are possible too. +## `attributes` +an attribute query string +## `flags` +a set of `FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +A `FileEnumerator` if successful, + `None` on error. Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously gets the requested information about the files +in a directory. The result is a `FileEnumerator` object that will +give out `FileInfo` objects for all the files in the directory. + +For more details, see `File::enumerate_children` which is +the synchronous version of this call. + +When the operation is finished, `callback` will be called. You can +then call `File::enumerate_children_finish` to get the result of +the operation. +## `attributes` +an attribute query string +## `flags` +a set of `FileQueryInfoFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call when the + request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an async enumerate children operation. +See `File::enumerate_children_async`. +## `res` +a `AsyncResult` + +# Returns + +a `FileEnumerator` or `None` + if an error occurred. + Free the returned object with `gobject::ObjectExt::unref`. + +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. +## `file2` +the second `File` + +# Returns + +`true` if `self` and `file2` are equal. + +Gets a `Mount` for the `File`. + +If the `FileIface` for `self` does not have a mount (e.g. +possibly a remote share), `error` will be set to `IOErrorEnum::NotFound` +and `None` will be returned. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `Mount` where the `self` is located + or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously gets the mount for the file. + +For more details, see `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 `File::find_enclosing_mount_finish` to +get the result of the operation. +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous find mount request. +See `File::find_enclosing_mount_async`. +## `res` +a `AsyncResult` + +# Returns + +`Mount` for given `self` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Gets the base name (the last component of the path) for a given `File`. + +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 `File::query_info`. + +This call does no blocking I/O. + +# Returns + +string containing the `File`'s + base name, or `None` if given `File` is invalid. The returned string + should be freed with `g_free` when no longer needed. + +Gets a child of `self` with basename equal to `name`. + +Note that the file with that specific name might not exist, but +you can still have a `File` that points to it. You can use this +for instance to create that file. + +This call does no blocking I/O. +## `name` +string containing the child's basename + +# Returns + +a `File` to a child specified by `name`. + Free the returned object with `gobject::ObjectExt::unref`. + +Gets the child of `self` for a given `display_name` (i.e. a UTF-8 +version of the name). If this function fails, it returns `None` +and `error` will be set. This is very useful when constructing a +`File` 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. +## `display_name` +string to a possible child + +# Returns + +a `File` to the specified child, or + `None` if the display name couldn't be converted. + Free the returned object with `gobject::ObjectExt::unref`. + +Gets the parent directory for the `self`. +If the `self` represents the root directory of the +file system, then `None` will be returned. + +This call does no blocking I/O. + +# Returns + +a `File` structure to the + parent of the given `File` or `None` if there is no parent. Free + the returned object with `gobject::ObjectExt::unref`. + +Gets the parse name of the `self`. +A parse name is a UTF-8 string that describes the +file such that one can get the `File` back using +`File::parse_name`. + +This is generally used to show the `File` 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. + +# Returns + +a string containing the `File`'s parse name. + The returned string should be freed with `g_free` + when no longer needed. + +Gets the local pathname for `File`, if one exists. If non-`None`, this is +guaranteed to be an absolute, canonical path. It might contain symlinks. + +This call does no blocking I/O. + +# Returns + +string containing the `File`'s path, + or `None` if no such path exists. The returned string should be freed + with `g_free` when no longer needed. + +Gets the path for `descendant` relative to `self`. + +This call does no blocking I/O. +## `descendant` +input `File` + +# Returns + +string with the relative path from + `descendant` to `self`, or `None` if `descendant` doesn't have `self` as + prefix. The returned string should be freed with `g_free` when + no longer needed. + +Gets the URI for the `self`. + +This call does no blocking I/O. + +# Returns + +a string containing the `File`'s URI. + The returned string should be freed with `g_free` + when no longer needed. + +Gets the URI scheme for a `File`. +RFC 3986 decodes the scheme as: + +```text +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +``` +Common schemes include "file", "http", "ftp", etc. + +This call does no blocking I/O. + +# Returns + +a string containing the URI scheme for the given + `File`. The returned string should be freed with `g_free` + when no longer needed. + +Checks if `self` has a parent, and optionally, if it is `parent`. + +If `parent` is `None` then this function returns `true` if `self` has any +parent at all. If `parent` is non-`None` then `true` is only returned +if `self` is an immediate child of `parent`. +## `parent` +the parent to check for, or `None` + +# Returns + +`true` if `self` is an immediate child of `parent` (or any parent in + the case that `parent` is `None`). + +Checks whether `self` has the prefix specified by `prefix`. + +In other words, if the names of initial elements of `self`'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 `File` is not a prefix of itself. If you want to check for +equality, use `File::equal`. + +This call does no I/O, as it works purely on names. As such it can +sometimes return `false` even if `self` is inside a `prefix` (from a +filesystem point of view), because the prefix of `self` is an alias +of `prefix`. +## `prefix` +input `File` + +# Returns + +`true` if the `files`'s parent, grandparent, etc is `prefix`, + `false` otherwise. + +Checks to see if a `File` has a given URI scheme. + +This call does no blocking I/O. +## `uri_scheme` +a string containing a URI scheme + +# Returns + +`true` if `File`'s backend supports the + given URI scheme, `false` if URI scheme is `None`, + not supported, or `File` is invalid. + +Creates a hash value for a `File`. + +This call does no blocking I/O. + +# Returns + +0 if `self` is not a valid `File`, otherwise an + integer that can be used as hash value for the `File`. + This function is intended for easily hashing a `File` to + add to a `glib::HashTable` or similar data structure. + +Checks to see if a file is native to the platform. + +A native file s 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 `File::get_path` will still return a native path. + +This call does no blocking I/O. + +# Returns + +`true` if `self` is native + +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 `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, `None` to ignore +## `contents` +a location to place the contents of the file +## `length` +a location to place the length of the contents of the file, + or `None` if the length is not needed +## `etag_out` +a location to place the current entity tag for the file, + or `None` if the entity tag is not needed + +# Returns + +`true` if the `self`'s contents were successfully loaded. + `false` if there were errors. + +Starts an asynchronous load of the `self`'s contents. + +For more details, see `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 +`File::load_contents_finish` with the `AsyncResult` returned by +the `callback`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous load of the `self`'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 `self`. +## `res` +a `AsyncResult` +## `contents` +a location to place the contents of the file +## `length` +a location to place the length of the contents of the file, + or `None` if the length is not needed +## `etag_out` +a location to place the current entity tag for the file, + or `None` if the entity tag is not needed + +# Returns + +`true` if the load was successful. If `false` and `error` is + present, it will be set appropriately. + +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 `File::load_contents_async`. This +operation can be finished by `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 `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, `None` to ignore +## `read_more_callback` +a `GFileReadMoreCallback` to receive partial data + and to specify whether further data should be read +## `callback` +a `GAsyncReadyCallback` to call when the request is satisfied +## `user_data` +the data to pass to the callback functions + +Finishes an asynchronous partial load operation that was started +with `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. +## `res` +a `AsyncResult` +## `contents` +a location to place the contents of the file +## `length` +a location to place the length of the contents of the file, + or `None` if the length is not needed +## `etag_out` +a location to place the current entity tag for the file, + or `None` if the entity tag is not needed + +# Returns + +`true` if the load was successful. If `false` and `error` is + present, it will be set appropriately. + +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 `File`. +To recursively create directories, see `File::make_directory_with_parents`. +This function will fail if the parent directory does not exist, setting +`error` to `IOErrorEnum::NotFound`. If the file system doesn't support +creating directories, this function will fail, setting `error` to +`IOErrorEnum::NotSupported`. + +For a local `File` the newly created directory will have the default +(current) ownership and permissions of the current process. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` on successful creation, `false` otherwise. + +Asynchronously creates a directory. + +Feature: `v2_38` + +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous directory creation, started with +`File::make_directory_async`. + +Feature: `v2_38` + +## `result` +a `AsyncResult` + +# Returns + +`true` on successful directory creation, `false` otherwise. + +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 +`IOErrorEnum::NotSupported`. If the directory itself already exists, +this function will fail setting `error` to `IOErrorEnum::Exists`, unlike +the similar `g_mkdir_with_parents`. + +For a local `File` the newly created directories will have the default +(current) ownership and permissions of the current process. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if all directories have been successfully created, `false` +otherwise. + +Creates a symbolic link named `self` which contains the string +`symlink_value`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `symlink_value` +a string with the path for the target + of the new symlink +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` on the creation of a new symlink, `false` otherwise. + +Recursively measures the disk usage of `self`. + +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_DISK_USAGE_REPORT_ALL_ERRORS` 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. + +Feature: `v2_38` + +## `flags` +`FileMeasureFlags` +## `cancellable` +optional `Cancellable` +## `progress_callback` +a `GFileMeasureProgressCallback` +## `progress_data` +user_data for `progress_callback` +## `disk_usage` +the number of bytes of disk space used +## `num_dirs` +the number of directories encountered +## `num_files` +the number of non-directories encountered + +# Returns + +`true` if successful, with the out parameters set. + `false` otherwise, with `error` set. + +Recursively measures the disk usage of `self`. + +This is the asynchronous version of `File::measure_disk_usage`. See +there for more information. + +Feature: `v2_38` + +## `flags` +`FileMeasureFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` +## `progress_callback` +a `GFileMeasureProgressCallback` +## `progress_data` +user_data for `progress_callback` +## `callback` +a `GAsyncReadyCallback` to call when complete +## `user_data` +the data to pass to callback function + +Collects the results from an earlier call to +`File::measure_disk_usage_async`. See `File::measure_disk_usage` for +more information. + +Feature: `v2_38` + +## `result` +the `AsyncResult` passed to your `GAsyncReadyCallback` +## `disk_usage` +the number of bytes of disk space used +## `num_dirs` +the number of directories encountered +## `num_files` +the number of non-directories encountered + +# Returns + +`true` if successful, with the out parameters set. + `false` otherwise, with `error` set. + +Obtains a file or directory monitor for the given file, +depending on the type of the file. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `flags` +a set of `FileMonitorFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileMonitor` for the given `self`, + or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Obtains a directory monitor for the given file. +This may fail if directory monitoring is not supported. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +It does not make sense for `flags` to contain +`FileMonitorFlags::WatchHardLinks`, 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 `File::monitor`. +## `flags` +a set of `FileMonitorFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileMonitor` for the given `self`, + or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +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 `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +If `flags` contains `FileMonitorFlags::WatchHardLinks` 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 `self` to be +reported. Using this flag may result in an increase in resource +usage, and may not have any effect depending on the `FileMonitor` +backend and/or filesystem type. +## `flags` +a set of `FileMonitorFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileMonitor` for the given `self`, + or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Starts a `mount_operation`, mounting the volume that contains +the file `self`. + +When this operation has completed, `callback` will be called with +`user_user` data, and the operation can be finalized with +`File::mount_enclosing_volume_finish`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `flags` +flags affecting the operation +## `mount_operation` +a `MountOperation` + or `None` to avoid user interaction +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes a mount operation started by `File::mount_enclosing_volume`. +## `result` +a `AsyncResult` + +# Returns + +`true` if successful. If an error has occurred, + this function will return `false` and set `error` + appropriately if present. + +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 `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +When the operation is finished, `callback` will be called. +You can then call `File::mount_mountable_finish` to get +the result of the operation. +## `flags` +flags affecting the operation +## `mount_operation` +a `MountOperation`, + or `None` to avoid user interaction +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes a mount operation. See `File::mount_mountable` for details. + +Finish an asynchronous mount operation that was started +with `File::mount_mountable`. +## `result` +a `AsyncResult` + +# Returns + +a `File` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Tries to move the file or directory `self` 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 `FileCopyFlags::Overwrite` is specified an already +existing `destination` file is overwritten. + +If the flag `FileCopyFlags::NofollowSymlinks` is specified then symlinks +will be copied as symlinks, otherwise the target of the +`self` symlink will be copied. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +If `progress_callback` is not `None`, 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 `self` file does not exist, then the `IOErrorEnum::NotFound` +error is returned, independent on the status of the `destination`. + +If `FileCopyFlags::Overwrite` is not specified and the target exists, +then the error `IOErrorEnum::Exists` is returned. + +If trying to overwrite a file over a directory, the `IOErrorEnum::IsDirectory` +error is returned. If trying to overwrite a directory with a directory the +`IOErrorEnum::WouldMerge` error is returned. + +If the source is a directory and the target does not exist, or +`FileCopyFlags::Overwrite` is specified and the target is a file, then +the `IOErrorEnum::WouldRecurse` error may be returned (if the native +move operation isn't available). +## `destination` +`File` pointing to the destination location +## `flags` +set of `FileCopyFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `progress_callback` +`GFileProgressCallback` + function for updates +## `progress_callback_data` +gpointer to user data for + the callback function + +# Returns + +`true` on successful move, `false` otherwise. + +Opens an existing file for reading and writing. The result is +a `FileIOStream` that can be used to read and write the contents +of the file. + +If `cancellable` is not `None`, then the operation can be cancelled +by triggering the cancellable object from another thread. If the +operation was cancelled, the error `IOErrorEnum::Cancelled` will be +returned. + +If the file does not exist, the `IOErrorEnum::NotFound` error will +be returned. If the file is a directory, the `IOErrorEnum::IsDirectory` +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. +## `cancellable` +a `Cancellable` + +# Returns + +`FileIOStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously opens `self` for reading and writing. + +For more details, see `File::open_readwrite` which is +the synchronous version of this call. + +When the operation is finished, `callback` will be called. +You can then call `File::open_readwrite_finish` to get +the result of the operation. +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous file read operation started with +`File::open_readwrite_async`. +## `res` +a `AsyncResult` + +# Returns + +a `FileIOStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Polls a file of type `FileType::Mountable`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +When the operation is finished, `callback` will be called. +You can then call `File::mount_mountable_finish` to get +the result of the operation. +## `cancellable` +optional `Cancellable` object, `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes a poll operation. See `File::poll_mountable` for details. + +Finish an asynchronous poll operation that was polled +with `File::poll_mountable`. +## `result` +a `AsyncResult` + +# Returns + +`true` if the operation finished successfully. `false` +otherwise. + +Returns the `AppInfo` that is registered as the default +application to handle the file specified by `self`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, `None` to ignore + +# Returns + +a `AppInfo` if the handle was found, + `None` if there were errors. + When you are done with it, release it with `gobject::ObjectExt::unref` + +Utility function to check if a particular file exists. This is +implemented using `File::query_info` and as such does blocking I/O. + +Note that in many cases it is racy to first check for file existence +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 `File::create` which will either +atomically create the file or fail with a `IOErrorEnum::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. +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the file exists (and can be detected without error), + `false` otherwise (or if cancelled). + +Utility function to inspect the `FileType` of a file. This is +implemented using `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. +## `flags` +a set of `FileQueryInfoFlags` passed to `File::query_info` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +The `FileType` of the file and `FileType::Unknown` + if the file does not exist + +Similar to `File::query_info`, but obtains information +about the filesystem the `self` 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 `None`, then the operation can be cancelled +by triggering the cancellable object from another thread. If the +operation was cancelled, the error `IOErrorEnum::Cancelled` will be +returned. + +If the file does not exist, the `IOErrorEnum::NotFound` error will +be returned. Other errors are possible too, and depend on what +kind of filesystem the file is on. +## `attributes` +an attribute query string +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileInfo` or `None` if there was an error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously gets the requested information about the filesystem +that the specified `self` is on. The result is a `FileInfo` object +that contains key-value attributes (such as type or size for the +file). + +For more details, see `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 `File::query_info_finish` to get the result of the +operation. +## `attributes` +an attribute query string +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous filesystem info query. +See `File::query_filesystem_info_async`. +## `res` +a `AsyncResult` + +# Returns + +`FileInfo` for given `self` + or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Gets the requested information about specified `self`. +The result is a `FileInfo` object that contains key-value +attributes (such as the type or size of the file). + +The `attributes` value is a string that specifies the file +attributes that should be gathered. It is not an error if +it's not possible to read a particular requested attribute +from a file - it just won't be set. `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 `None`, then the operation can be cancelled +by triggering the cancellable object from another thread. If the +operation was cancelled, the error `IOErrorEnum::Cancelled` will be +returned. + +For symlinks, normally the information about the target of the +symlink is returned, rather than information about the symlink +itself. However if you pass `FileQueryInfoFlags::NofollowSymlinks` +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 `IOErrorEnum::NotFound` error will be +returned. Other errors are possible too, and depend on what kind of +filesystem the file is on. +## `attributes` +an attribute query string +## `flags` +a set of `FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileInfo` for the given `self`, or `None` + on error. Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously gets the requested information about specified `self`. +The result is a `FileInfo` object that contains key-value attributes +(such as type or size for the file). + +For more details, see `File::query_info` which is the synchronous +version of this call. + +When the operation is finished, `callback` will be called. You can +then call `File::query_info_finish` to get the result of the operation. +## `attributes` +an attribute query string +## `flags` +a set of `FileQueryInfoFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call when the + request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous file info query. +See `File::query_info_async`. +## `res` +a `AsyncResult` + +# Returns + +`FileInfo` for given `self` + or `None` on error. Free the returned object with + `gobject::ObjectExt::unref`. + +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 `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileAttributeInfoList` describing the settable attributes. + When you are done with it, release it with + `FileAttributeInfoList::unref` + +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 `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileAttributeInfoList` describing the writable namespaces. + When you are done with it, release it with + `FileAttributeInfoList::unref` + +Opens a file for reading. The result is a `FileInputStream` that +can be used to read the contents of the file. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +If the file does not exist, the `IOErrorEnum::NotFound` error will be +returned. If the file is a directory, the `IOErrorEnum::IsDirectory` +error will be returned. Other errors are possible too, and depend +on what kind of filesystem the file is on. +## `cancellable` +a `Cancellable` + +# Returns + +`FileInputStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously opens `self` for reading. + +For more details, see `File::read` which is +the synchronous version of this call. + +When the operation is finished, `callback` will be called. +You can then call `File::read_finish` to get the result +of the operation. +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous file read operation started with +`File::read_async`. +## `res` +a `AsyncResult` + +# Returns + +a `FileInputStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +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 `FileCreateFlags::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 `None`, then the operation can be cancelled +by triggering the cancellable object from another thread. If the +operation was cancelled, the error `IOErrorEnum::Cancelled` will be +returned. + +If you pass in a non-`None` `etag` value and `self` already exists, then +this value is compared to the current entity tag of the file, and if +they differ an `IOErrorEnum::WrongEtag` error is returned. This +generally means that the file has been changed since you last read +it. You can get the new etag from `FileOutputStream::get_etag` +after you've finished writing and closed the `FileOutputStream`. When +you load a new file you can use `FileInputStream::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 `IOErrorEnum::CantCreateBackup` 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 `IOErrorEnum::IsDirectory` error will +be returned, and if the file is some other form of non-regular file +then a `IOErrorEnum::NotRegularFile` error will be returned. Some +file systems don't allow all file names, and may return an +`IOErrorEnum::InvalidFilename` error, and if the name is to long +`IOErrorEnum::FilenameTooLong` will be returned. Other errors are +possible too, and depend on what kind of filesystem the file is on. +## `etag` +an optional [entity tag][gfile-etag] + for the current `File`, or `None` to ignore +## `make_backup` +`true` if a backup should be created +## `flags` +a set of `FileCreateFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileOutputStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously overwrites the file, replacing the contents, +possibly creating a backup copy of the file first. + +For more details, see `File::replace` which is +the synchronous version of this call. + +When the operation is finished, `callback` will be called. +You can then call `File::replace_finish` to get the result +of the operation. +## `etag` +an [entity tag][gfile-etag] for the current `File`, + or `None` to ignore +## `make_backup` +`true` if a backup should be created +## `flags` +a set of `FileCreateFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Replaces the contents of `self` with `contents` of `length` bytes. + +If `etag` is specified (not `None`), any existing file must have that etag, +or the error `IOErrorEnum::WrongEtag` will be returned. + +If `make_backup` is `true`, this function will attempt to make a backup +of `self`. Internally, it uses `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 `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::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. +## `contents` +a string containing the new contents for `self` +## `length` +the length of `contents` in bytes +## `etag` +the old [entity-tag][gfile-etag] for the document, + or `None` +## `make_backup` +`true` if a backup should be created +## `flags` +a set of `FileCreateFlags` +## `new_etag` +a location to a new [entity tag][gfile-etag] + for the document. This should be freed with `g_free` when no longer + needed, or `None` +## `cancellable` +optional `Cancellable` object, `None` to ignore + +# Returns + +`true` if successful. If an error has occurred, this function + will return `false` and set `error` appropriately if present. + +Starts an asynchronous replacement of `self` 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 +`File::replace_contents_finish`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +If `make_backup` is `true`, this function will attempt to +make a backup of `self`. + +Note that no copy of `content` will be made, so it must stay valid +until `callback` is called. See `File::replace_contents_bytes_async` +for a `glib::Bytes` version that will automatically hold a reference to the +contents (without copying) for the duration of the call. +## `contents` +string of contents to replace the file with +## `length` +the length of `contents` in bytes +## `etag` +a new [entity tag][gfile-etag] for the `self`, or `None` +## `make_backup` +`true` if a backup should be created +## `flags` +a set of `FileCreateFlags` +## `cancellable` +optional `Cancellable` object, `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call when the request is satisfied +## `user_data` +the data to pass to callback function + +Same as `File::replace_contents_async` but takes a `glib::Bytes` input instead. +This function will keep a ref on `contents` until the operation is done. +Unlike `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 +`File::replace_contents_finish`. + +Feature: `v2_40` + +## `contents` +a `glib::Bytes` +## `etag` +a new [entity tag][gfile-etag] for the `self`, or `None` +## `make_backup` +`true` if a backup should be created +## `flags` +a set of `FileCreateFlags` +## `cancellable` +optional `Cancellable` object, `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous replace of the given `self`. See +`File::replace_contents_async`. Sets `new_etag` to the new entity +tag for the document, if present. +## `res` +a `AsyncResult` +## `new_etag` +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 `None` + +# Returns + +`true` on success, `false` on failure. + +Finishes an asynchronous file replace operation started with +`File::replace_async`. +## `res` +a `AsyncResult` + +# Returns + +a `FileOutputStream`, or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +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 `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. +## `etag` +an optional [entity tag][gfile-etag] + for the current `File`, or `None` to ignore +## `make_backup` +`true` if a backup should be created +## `flags` +a set of `FileCreateFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `FileIOStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously overwrites the file in read-write mode, +replacing the contents, possibly creating a backup copy +of the file first. + +For more details, see `File::replace_readwrite` which is +the synchronous version of this call. + +When the operation is finished, `callback` will be called. +You can then call `File::replace_readwrite_finish` to get +the result of the operation. +## `etag` +an [entity tag][gfile-etag] for the current `File`, + or `None` to ignore +## `make_backup` +`true` if a backup should be created +## `flags` +a set of `FileCreateFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous file replace operation started with +`File::replace_readwrite_async`. +## `res` +a `AsyncResult` + +# Returns + +a `FileIOStream`, or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Resolves a relative path for `self` to an absolute path. + +This call does no blocking I/O. +## `relative_path` +a given relative path string + +# Returns + +`File` to the resolved path. + `None` if `relative_path` is `None` or if `self` is invalid. + Free the returned object with `gobject::ObjectExt::unref`. + +Sets an attribute in the file with attribute name `attribute` to `value`. + +Some attributes can be unset by setting `attribute` to +`FileAttributeType::Invalid` and `value_p` to `None`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `attribute` +a string containing the attribute's name +## `type_` +The type of the attribute +## `value_p` +a pointer to the value (or the pointer + itself if the type is a pointer type) +## `flags` +a set of `FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the attribute was set, `false` otherwise. + +Sets `attribute` of type `FileAttributeType::ByteString` to `value`. +If `attribute` is of a different type, this operation will fail, +returning `false`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `attribute` +a string containing the attribute's name +## `value` +a string containing the attribute's new value +## `flags` +a `FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the `attribute` was successfully set to `value` + in the `self`, `false` otherwise. + +Sets `attribute` of type `FileAttributeType::Int32` to `value`. +If `attribute` is of a different type, this operation will fail. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `attribute` +a string containing the attribute's name +## `value` +a `gint32` containing the attribute's new value +## `flags` +a `FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the `attribute` was successfully set to `value` + in the `self`, `false` otherwise. + +Sets `attribute` of type `FileAttributeType::Int64` to `value`. +If `attribute` is of a different type, this operation will fail. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `attribute` +a string containing the attribute's name +## `value` +a `guint64` containing the attribute's new value +## `flags` +a `FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the `attribute` was successfully set, `false` otherwise. + +Sets `attribute` of type `FileAttributeType::String` to `value`. +If `attribute` is of a different type, this operation will fail. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `attribute` +a string containing the attribute's name +## `value` +a string containing the attribute's value +## `flags` +`FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the `attribute` was successfully set, `false` otherwise. + +Sets `attribute` of type `FileAttributeType::Uint32` to `value`. +If `attribute` is of a different type, this operation will fail. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `attribute` +a string containing the attribute's name +## `value` +a `guint32` containing the attribute's new value +## `flags` +a `FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the `attribute` was successfully set to `value` + in the `self`, `false` otherwise. + +Sets `attribute` of type `FileAttributeType::Uint64` to `value`. +If `attribute` is of a different type, this operation will fail. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `attribute` +a string containing the attribute's name +## `value` +a `guint64` containing the attribute's new value +## `flags` +a `FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` if the `attribute` was successfully set to `value` + in the `self`, `false` otherwise. + +Asynchronously sets the attributes of `self` with `info`. + +For more details, see `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 `File::set_attributes_finish` to get +the result of the operation. +## `info` +a `FileInfo` +## `flags` +a `FileQueryInfoFlags` +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` +## `user_data` +a `gpointer` + +Finishes setting an attribute started in `File::set_attributes_async`. +## `result` +a `AsyncResult` +## `info` +a `FileInfo` + +# Returns + +`true` if the attributes were set correctly, `false` otherwise. + +Tries to set all attributes in the `FileInfo` 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 +`FileAttributeStatus::ErrorSetting`, which means you can +also detect further errors. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `info` +a `FileInfo` +## `flags` +`FileQueryInfoFlags` +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`false` if there was any error, `true` otherwise. + +Renames `self` 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 `self` 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 `File::set_display_name`. + +On success the resulting converted filename is returned. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `display_name` +a string +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +a `File` specifying what `self` was renamed to, + or `None` if there was an error. + Free the returned object with `gobject::ObjectExt::unref`. + +Asynchronously sets the display name for a given `File`. + +For more details, see `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 `File::set_display_name_finish` to get +the result of the operation. +## `display_name` +a string +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes setting a display name started with +`File::set_display_name_async`. +## `res` +a `AsyncResult` + +# Returns + +a `File` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref`. + +Starts a file of type `FileType::Mountable`. +Using `start_operation`, you can request callbacks when, for instance, +passwords are needed during authentication. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +When the operation is finished, `callback` will be called. +You can then call `File::mount_mountable_finish` to get +the result of the operation. +## `flags` +flags affecting the operation +## `start_operation` +a `MountOperation`, or `None` to avoid user interaction +## `cancellable` +optional `Cancellable` object, `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes a start operation. See `File::start_mountable` for details. + +Finish an asynchronous start operation that was started +with `File::start_mountable`. +## `result` +a `AsyncResult` + +# Returns + +`true` if the operation finished successfully. `false` +otherwise. + +Stops a file of type `FileType::Mountable`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +When the operation is finished, `callback` will be called. +You can then call `File::stop_mountable_finish` to get +the result of the operation. +## `flags` +flags affecting the operation +## `mount_operation` +a `MountOperation`, + or `None` to avoid user interaction. +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes an stop operation, see `File::stop_mountable` for details. + +Finish an asynchronous stop operation that was started +with `File::stop_mountable`. +## `result` +a `AsyncResult` + +# Returns + +`true` if the operation finished successfully. + `false` otherwise. + +Checks if `self` supports +[thread-default contexts][g-main-context-push-thread-default-context]. +If this returns `false`, you cannot perform asynchronous operations on +`self` in a thread that has a thread-default context. + +# Returns + +Whether or not `self` supports thread-default contexts. + +Sends `self` 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 +`IOErrorEnum::NotSupported` error. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. +## `cancellable` +optional `Cancellable` object, + `None` to ignore + +# Returns + +`true` on successful trash, `false` otherwise. + +Asynchronously sends `self` to the Trash location, if possible. + +Feature: `v2_38` + +## `io_priority` +the [I/O priority][io-priority] of the request +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied +## `user_data` +the data to pass to callback function + +Finishes an asynchronous file trashing operation, started with +`File::trash_async`. + +Feature: `v2_38` + +## `result` +a `AsyncResult` + +# Returns + +`true` on successful trash, `false` otherwise. + +Unmounts a file of type G_FILE_TYPE_MOUNTABLE. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +When the operation is finished, `callback` will be called. +You can then call `File::unmount_mountable_finish` to get +the result of the operation. + +# Deprecated since 2.22 + +Use `File::unmount_mountable_with_operation` instead. +## `flags` +flags affecting the operation +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes an unmount operation, see `File::unmount_mountable` for details. + +Finish an asynchronous unmount operation that was started +with `File::unmount_mountable`. + +# Deprecated since 2.22 + +Use `File::unmount_mountable_with_operation_finish` + instead. +## `result` +a `AsyncResult` + +# Returns + +`true` if the operation finished successfully. + `false` otherwise. + +Unmounts a file of type `FileType::Mountable`. + +If `cancellable` is not `None`, then the operation can be cancelled by +triggering the cancellable object from another thread. If the operation +was cancelled, the error `IOErrorEnum::Cancelled` will be returned. + +When the operation is finished, `callback` will be called. +You can then call `File::unmount_mountable_finish` to get +the result of the operation. +## `flags` +flags affecting the operation +## `mount_operation` +a `MountOperation`, + or `None` to avoid user interaction +## `cancellable` +optional `Cancellable` object, + `None` to ignore +## `callback` +a `GAsyncReadyCallback` to call + when the request is satisfied, or `None` +## `user_data` +the data to pass to callback function + +Finishes an unmount operation, +see `File::unmount_mountable_with_operation` for details. + +Finish an asynchronous unmount operation that was started +with `File::unmount_mountable_with_operation`. +## `result` +a `AsyncResult` + +# Returns + +`true` if the operation finished successfully. + `false` otherwise. + +Functionality for manipulating basic metadata for files. `FileInfo` +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 `FileInfo` for a `File`, use `File::query_info` (or its +async variant). To obtain a `FileInfo` for a file input or output +stream, use `FileInputStream::query_info` or +`FileOutputStream::query_info` (or their async variants). + +To change the actual attributes of a file, you should then set the +attribute in the `FileInfo` and call `File::set_attributes_from_info` +or `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 `FileInfoExt::set_size`. +You may call `File::query_settable_attributes` and +`File::query_writable_namespaces` to discover the settable attributes +of a particular file at runtime. + +`FileAttributeMatcher` allows for searching through a `FileInfo` for +attributes. + +# Implements + +[`FileInfoExt`](trait.FileInfoExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `FileInfo` methods. + +# Implementors + +[`FileInfo`](struct.FileInfo.html) + +Creates a new file info structure. + +# Returns + +a `FileInfo`. + +Clears the status information from `self`. + +First clears all of the [GFileAttribute][gio-GFileAttribute] of `dest_info`, +and then copies all of the file attributes from `self` to `dest_info`. +## `dest_info` +destination to copy attributes to. + +Duplicates a file info structure. + +# Returns + +a duplicate `FileInfo` of `self`. + +Gets the value of a attribute, formated as a string. +This escapes things as needed to make the string valid +utf8. +## `attribute` +a file attribute key. + +# Returns + +a UTF-8 string associated with the given `attribute`. + When you're done with the string it must be freed with `g_free`. + +Gets the value of a boolean attribute. If the attribute does not +contain a boolean value, `false` will be returned. +## `attribute` +a file attribute key. + +# Returns + +the boolean value contained within the attribute. + +Gets the value of a byte string attribute. If the attribute does +not contain a byte string, `None` will be returned. +## `attribute` +a file attribute key. + +# Returns + +the contents of the `attribute` value as a byte string, or +`None` otherwise. + +Gets the attribute type, value and status for an attribute key. +## `attribute` +a file attribute key +## `type_` +return location for the attribute type, or `None` +## `value_pp` +return location for the + attribute value, or `None`; the attribute value will not be `None` +## `status` +return location for the attribute status, or `None` + +# Returns + +`true` if `self` has an attribute named `attribute`, + `false` otherwise. + +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. +## `attribute` +a file attribute key. + +# Returns + +a signed 32-bit integer from the attribute. + +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. +## `attribute` +a file attribute key. + +# Returns + +a signed 64-bit integer from the attribute. + +Gets the value of a `gobject::Object` attribute. If the attribute does +not contain a `gobject::Object`, `None` will be returned. +## `attribute` +a file attribute key. + +# Returns + +a `gobject::Object` associated with the given `attribute`, or +`None` otherwise. + +Gets the attribute status for an attribute key. +## `attribute` +a file attribute key + +# Returns + +a `FileAttributeStatus` for the given `attribute`, or + `FileAttributeStatus::Unset` if the key is invalid. + +Gets the value of a string attribute. If the attribute does +not contain a string, `None` will be returned. +## `attribute` +a file attribute key. + +# Returns + +the contents of the `attribute` value as a UTF-8 string, or +`None` otherwise. + +Gets the value of a stringv attribute. If the attribute does +not contain a stringv, `None` will be returned. +## `attribute` +a file attribute key. + +# Returns + +the contents of the `attribute` value as a stringv, or +`None` otherwise. Do not free. These returned strings are UTF-8. + +Gets the attribute type for an attribute key. +## `attribute` +a file attribute key. + +# Returns + +a `FileAttributeType` for the given `attribute`, or +`FileAttributeType::Invalid` if the key is not set. + +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. +## `attribute` +a file attribute key. + +# Returns + +an unsigned 32-bit integer from the attribute. + +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. +## `attribute` +a file attribute key. + +# Returns + +a unsigned 64-bit integer from the attribute. + +Gets the file's content type. + +# Returns + +a string containing the file's content type. + +Returns the `glib::DateTime` 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, `None` is returned. + +Feature: `v2_36` + + +# Returns + +a `glib::DateTime`, or `None`. + +Gets a display name for a file. + +# Returns + +a string containing the display name. + +Gets the edit name for a file. + +# Returns + +a string containing the edit name. + +Gets the [entity tag][gfile-etag] for a given +`FileInfo`. See `G_FILE_ATTRIBUTE_ETAG_VALUE`. + +# Returns + +a string containing the value of the "etag:value" attribute. + +Gets a file's type (whether it is a regular file, symlink, etc). +This is different from the file's content type, see `FileInfoExt::get_content_type`. + +# Returns + +a `FileType` for the given file. + +Gets the icon for a file. + +# Returns + +`Icon` for the given `self`. + +Checks if a file is a backup file. + +# Returns + +`true` if file is a backup file, `false` otherwise. + +Checks if a file is hidden. + +# Returns + +`true` if the file is a hidden file, `false` otherwise. + +Checks if a file is a symlink. + +# Returns + +`true` if the given `self` is a symlink. + +Gets the modification time of the current `self` and sets it +in `result`. +## `result` +a `glib::TimeVal`. + +Gets the name for a file. + +# Returns + +a string containing the file name. + +Gets the file's size. + +# Returns + +a `goffset` containing the file's size. + +Gets the value of the sort_order attribute from the `FileInfo`. +See `G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. + +# Returns + +a `gint32` containing the value of the "standard::sort_order" attribute. + +Gets the symbolic icon for a file. + +Feature: `v2_34` + + +# Returns + +`Icon` for the given `self`. + +Gets the symlink target for a given `FileInfo`. + +# Returns + +a string containing the symlink target. + +Checks if a file info structure has an attribute named `attribute`. +## `attribute` +a file attribute key. + +# Returns + +`true` if `Ginfo` has an attribute named `attribute`, + `false` otherwise. + +Checks if a file info structure has an attribute in the +specified `name_space`. +## `name_space` +a file attribute namespace. + +# Returns + +`true` if `Ginfo` has an attribute in `name_space`, + `false` otherwise. + +Lists the file info structure's attributes. +## `name_space` +a file attribute key's namespace, or `None` to list + all attributes. + +# Returns + +a +null-terminated array of strings of all of the possible attribute +types for the given `name_space`, or `None` on error. + +Removes all cases of `attribute` from `self` if it exists. +## `attribute` +a file attribute key. + +Sets the `attribute` to contain the given value, if possible. To unset the +attribute, use `G_ATTRIBUTE_TYPE_INVALID` for `type_`. +## `attribute` +a file attribute key. +## `type_` +a `FileAttributeType` +## `value_p` +pointer to the value + +Sets the `attribute` to contain the given `attr_value`, +if possible. +## `attribute` +a file attribute key. +## `attr_value` +a boolean value. + +Sets the `attribute` to contain the given `attr_value`, +if possible. +## `attribute` +a file attribute key. +## `attr_value` +a byte string. + +Sets the `attribute` to contain the given `attr_value`, +if possible. +## `attribute` +a file attribute key. +## `attr_value` +a signed 32-bit integer + +Sets the `attribute` to contain the given `attr_value`, +if possible. +## `attribute` +attribute name to set. +## `attr_value` +int64 value to set attribute to. + +Sets `mask` on `self` to match specific attribute types. +## `mask` +a `FileAttributeMatcher`. + +Sets the `attribute` to contain the given `attr_value`, +if possible. +## `attribute` +a file attribute key. +## `attr_value` +a `gobject::Object`. + +Sets the attribute status for an attribute key. This is only +needed by external code that implement `File::set_attributes_from_info` +or similar functions. + +The attribute must exist in `self` for this to work. Otherwise `false` +is returned and `self` is unchanged. +## `attribute` +a file attribute key +## `status` +a `FileAttributeStatus` + +# Returns + +`true` if the status was changed, `false` if the key was not set. + +Sets the `attribute` to contain the given `attr_value`, +if possible. +## `attribute` +a file attribute key. +## `attr_value` +a UTF-8 string. + +Sets the `attribute` to contain the given `attr_value`, +if possible. + +Sinze: 2.22 +## `attribute` +a file attribute key +## `attr_value` +a `None` terminated array of UTF-8 strings. + +Sets the `attribute` to contain the given `attr_value`, +if possible. +## `attribute` +a file attribute key. +## `attr_value` +an unsigned 32-bit integer. + +Sets the `attribute` to contain the given `attr_value`, +if possible. +## `attribute` +a file attribute key. +## `attr_value` +an unsigned 64-bit integer. + +Sets the content type attribute for a given `FileInfo`. +See `G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE`. +## `content_type` +a content type. See [GContentType][gio-GContentType] + +Sets the display name for the current `FileInfo`. +See `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME`. +## `display_name` +a string containing a display name. + +Sets the edit name for the current file. +See `G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME`. +## `edit_name` +a string containing an edit name. + +Sets the file type in a `FileInfo` to `type_`. +See `G_FILE_ATTRIBUTE_STANDARD_TYPE`. +## `type_` +a `FileType`. + +Sets the icon for a given `FileInfo`. +See `G_FILE_ATTRIBUTE_STANDARD_ICON`. +## `icon` +a `Icon`. + +Sets the "is_hidden" attribute in a `FileInfo` according to `is_hidden`. +See `G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN`. +## `is_hidden` +a `gboolean`. + +Sets the "is_symlink" attribute in a `FileInfo` according to `is_symlink`. +See `G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK`. +## `is_symlink` +a `gboolean`. + +Sets the `G_FILE_ATTRIBUTE_TIME_MODIFIED` attribute in the file +info to the given time value. +## `mtime` +a `glib::TimeVal`. + +Sets the name attribute for the current `FileInfo`. +See `G_FILE_ATTRIBUTE_STANDARD_NAME`. +## `name` +a string containing a name. + +Sets the `G_FILE_ATTRIBUTE_STANDARD_SIZE` attribute in the file info +to the given size. +## `size` +a `goffset` containing the file's size. + +Sets the sort order attribute in the file info structure. See +`G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. +## `sort_order` +a sort order integer. + +Sets the symbolic icon for a given `FileInfo`. +See `G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON`. + +Feature: `v2_34` + +## `icon` +a `Icon`. + +Sets the `G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET` attribute in the file info +to the given symlink target. +## `symlink_target` +a static string containing a path to a symlink target. + +Unsets a mask set by `FileInfoExt::set_attribute_mask`, if one +is set. + +Indicates the file's on-disk type. + +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. + +`Icon` 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. + +`Icon` does not provide the actual pixmap for the icon as this is out +of GIO's scope, however implementations of `Icon` may contain the name +of an icon (see `ThemedIcon`), or the path to an icon (see `LoadableIcon`). + +To obtain a hash of a `Icon`, see `Icon::hash`. + +To check if two `GIcons` are equal, see `Icon::equal`. + +For serializing a `Icon`, use `Icon::serialize` and +`Icon::deserialize`. + +If you want to consume `Icon` (for example, in a toolkit) you must +be prepared to handle at least the three following cases: +`LoadableIcon`, `ThemedIcon` and `EmblemedIcon`. It may also make +sense to have fast-paths for other cases (like handling ``GdkPixbuf`` +directly, for example) but all compliant `Icon` implementations +outside of GIO must implement `LoadableIcon`. + +If your application or library provides one or more `Icon` +implementations you need to ensure that your new implementation also +implements `LoadableIcon`. Additionally, you must provide an +implementation of `Icon::serialize` that gives a result that is +understood by `Icon::deserialize`, yielding one of the built-in icon +types. + +# Implements + +[`IconExt`](trait.IconExt.html) + +Trait containing all `Icon` methods. + +# Implementors + +[`Icon`](struct.Icon.html), [`ThemedIcon`](struct.ThemedIcon.html) + +Deserializes a `Icon` previously serialized using `Icon::serialize`. + +Feature: `v2_38` + +## `value` +a `glib::Variant` created with `Icon::serialize` + +# Returns + +a `Icon`, or `None` when deserialization fails. + +Gets a hash for an icon. +## `icon` +`gconstpointer` to an icon object. + +# Returns + +a `guint` containing a hash for the `icon`, suitable for +use in a `glib::HashTable` or similar data structure. + +Generate a `Icon` instance from `str`. This function can fail if +`str` is not valid - see `Icon::to_string` for discussion. + +If your application or library provides one or more `Icon` +implementations you need to ensure that each `glib::Type` is registered +with the type system prior to calling `Icon::new_for_string`. +## `str` +A string obtained via `Icon::to_string`. + +# Returns + +An object implementing the `Icon` + interface or `None` if `error` is set. + +Checks if two icons are equal. +## `icon2` +pointer to the second `Icon`. + +# Returns + +`true` if `self` is equal to `icon2`. `false` otherwise. + +Serializes a `Icon` into a `glib::Variant`. An equivalent `Icon` can be retrieved +back by calling `Icon::deserialize` on the returned value. +As serialization will avoid using raw icon data when possible, it only +makes sense to transfer the `glib::Variant` between processes on the same machine, +(as opposed to over the network), and within the same file system namespace. + +Feature: `v2_38` + + +# Returns + +a `glib::Variant`, or `None` when serialization fails. + +Generates a textual representation of `self` that can be used for +serialization such as when passing `self` to a different process or +saving it to persistent storage. Use `Icon::new_for_string` to +get `self` back from the returned string. + +The encoding of the returned string is proprietary to `Icon` except +in the following two cases + +- If `self` is a `FileIcon`, the returned string is a native path + (such as `/path/to/my icon.png`) without escaping + if the `File` for `self` is a native file. If the file is not + native, the returned string is the result of `File::get_uri` + (such as `sftp://path/to/my%20icon.png`). + +- If `self` is a `ThemedIcon` with exactly one name, the encoding is + simply the name (such as `network-server`). + +# Returns + +An allocated NUL-terminated UTF8 string or +`None` if `self` can't be serialized. Use `g_free` to free. + +`Menu` is a simple implementation of `MenuModel`. +You populate a `Menu` by adding `MenuItem` instances to it. + +There are some convenience functions to allow you to directly +add items (avoiding `MenuItem`) for the common cases. To add +a regular item, use `MenuExt::insert`. To add a section, use +`MenuExt::insert_section`. To add a submenu, use +`MenuExt::insert_submenu`. + +# Implements + +[`MenuExt`](trait.MenuExt.html), [`MenuModelExt`](trait.MenuModelExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Menu` methods. + +# Implementors + +[`Menu`](struct.Menu.html) + +Creates a new `Menu`. + +The new menu has no items. + +# Returns + +a new `Menu` + +Convenience function for appending a normal menu item to the end of +`self`. Combine `MenuItem::new` and `MenuExt::insert_item` for a more +flexible alternative. +## `label` +the section label, or `None` +## `detailed_action` +the detailed action string, or `None` + +Appends `item` to the end of `self`. + +See `MenuExt::insert_item` for more information. +## `item` +a `MenuItem` to append + +Convenience function for appending a section menu item to the end of +`self`. Combine `MenuItem::new_section` and `MenuExt::insert_item` for a +more flexible alternative. +## `label` +the section label, or `None` +## `section` +a `MenuModel` with the items of the section + +Convenience function for appending a submenu menu item to the end of +`self`. Combine `MenuItem::new_submenu` and `MenuExt::insert_item` for a +more flexible alternative. +## `label` +the section label, or `None` +## `submenu` +a `MenuModel` with the items of the submenu + +Marks `self` 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 `Menu` API must no +longer be used. + +This function causes `MenuModelExt::is_mutable` to begin returning +`false`, which has some positive performance implications. + +Convenience function for inserting a normal menu item into `self`. +Combine `MenuItem::new` and `MenuExt::insert_item` for a more flexible +alternative. +## `position` +the position at which to insert the item +## `label` +the section label, or `None` +## `detailed_action` +the detailed action string, or `None` + +Inserts `item` into `self`. + +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 `self`. +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 `MenuExt::insert`, `MenuExt::insert_section` and +`MenuExt::insert_submenu` as well as "prepend" and "append" variants of +each of these functions. +## `position` +the position at which to insert the item +## `item` +the `MenuItem` to insert + +Convenience function for inserting a section menu item into `self`. +Combine `MenuItem::new_section` and `MenuExt::insert_item` for a more +flexible alternative. +## `position` +the position at which to insert the item +## `label` +the section label, or `None` +## `section` +a `MenuModel` with the items of the section + +Convenience function for inserting a submenu menu item into `self`. +Combine `MenuItem::new_submenu` and `MenuExt::insert_item` for a more +flexible alternative. +## `position` +the position at which to insert the item +## `label` +the section label, or `None` +## `submenu` +a `MenuModel` with the items of the submenu + +Convenience function for prepending a normal menu item to the start +of `self`. Combine `MenuItem::new` and `MenuExt::insert_item` for a more +flexible alternative. +## `label` +the section label, or `None` +## `detailed_action` +the detailed action string, or `None` + +Prepends `item` to the start of `self`. + +See `MenuExt::insert_item` for more information. +## `item` +a `MenuItem` to prepend + +Convenience function for prepending a section menu item to the start +of `self`. Combine `MenuItem::new_section` and `MenuExt::insert_item` for +a more flexible alternative. +## `label` +the section label, or `None` +## `section` +a `MenuModel` with the items of the section + +Convenience function for prepending a submenu menu item to the start +of `self`. Combine `MenuItem::new_submenu` and `MenuExt::insert_item` for +a more flexible alternative. +## `label` +the section label, or `None` +## `submenu` +a `MenuModel` 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). +## `position` +the position of the item to remove + +Removes all items in the menu. + +Feature: `v2_38` + + +`MenuAttributeIter` is an opaque structure type. You must access it +using the functions below. + +# Implements + +[`MenuAttributeIterExt`](trait.MenuAttributeIterExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `MenuAttributeIter` methods. + +# Implementors + +[`MenuAttributeIter`](struct.MenuAttributeIter.html) + +Gets the name of the attribute at the current iterator position, as +a string. + +The iterator is not advanced. + +# Returns + +the name of the attribute + +This function combines `MenuAttributeIterExt::next` with +`MenuAttributeIterExt::get_name` and `MenuAttributeIterExt::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, +`MenuAttributeIterExt::get_name` and `MenuAttributeIterExt::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 `glib::Variant::unref` when it is no longer in use. +## `out_name` +the type of the attribute +## `value` +the attribute value + +# Returns + +`true` on success, or `false` if there is no additional + attribute + +Gets the value of the attribute at the current iterator position. + +The iterator is not advanced. + +# Returns + +the value of the current attribute + +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). + +# Returns + +`true` on success, or `false` when there are no more attributes + +`MenuItem` is an opaque structure type. You must access it using the +functions below. + +# Implements + +[`MenuItemExt`](trait.MenuItemExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `MenuItem` methods. + +# Implementors + +[`MenuItem`](struct.MenuItem.html) + +Creates a new `MenuItem`. + +If `label` is non-`None` it is used to set the "label" attribute of the +new item. + +If `detailed_action` is non-`None` it is used to set the "action" and +possibly the "target" attribute of the new item. See +`MenuItemExt::set_detailed_action` for more information. +## `label` +the section label, or `None` +## `detailed_action` +the detailed action string, or `None` + +# Returns + +a new `MenuItem` + +Creates a `MenuItem` as an exact copy of an existing menu item in a +`MenuModel`. + +`item_index` must be valid (ie: be sure to call +`MenuModelExt::get_n_items` first). + +Feature: `v2_34` + +## `model` +a `MenuModel` +## `item_index` +the index of an item in `model` + +# Returns + +a new `MenuItem`. + +Creates a new `MenuItem` representing a section. + +This is a convenience API around `MenuItem::new` and +`MenuItemExt::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-`None` 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 `Menu` 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: + +```text + +
+ + +
+
+ + + +
+ +``` + +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). + +```text + + + + + + + + + + + + + + + +``` +## `label` +the section label, or `None` +## `section` +a `MenuModel` with the items of the section + +# Returns + +a new `MenuItem` + +Creates a new `MenuItem` representing a submenu. + +This is a convenience API around `MenuItem::new` and +`MenuItemExt::set_submenu`. +## `label` +the section label, or `None` +## `submenu` +a `MenuModel` with the items of the submenu + +# Returns + +a new `MenuItem` + +Queries the named `attribute` on `self`. + +If the attribute exists and matches the `glib::VariantType` 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. + +Feature: `v2_34` + +## `attribute` +the attribute name to query +## `format_string` +a `glib::Variant` format string + +# Returns + +`true` if the named attribute was found with the expected + type + +Queries the named `attribute` on `self`. + +If `expected_type` is specified and the attribute does not have this +type, `None` is returned. `None` is also returned if the attribute +simply does not exist. + +Feature: `v2_34` + +## `attribute` +the attribute name to query +## `expected_type` +the expected type of the attribute + +# Returns + +the attribute value, or `None` + +Queries the named `link` on `self`. + +Feature: `v2_34` + +## `link` +the link name to query + +# Returns + +the link, or `None` + +Sets or unsets the "action" and "target" attributes of `self`. + +If `action` is `None` then both the "action" and "target" attributes +are unset (and `format_string` is ignored along with the positional +parameters). + +If `action` is non-`None` then the "action" attribute is set. +`format_string` is then inspected. If it is non-`None` then the proper +position parameters are collected to create a `glib::Variant` instance to +use as the target value. If it is `None` then the positional +parameters are ignored and the "target" attribute is unset. + +See also `MenuItemExt::set_action_and_target_value` for an equivalent +call that directly accepts a `glib::Variant`. See +`MenuItemExt::set_detailed_action` for a more convenient version that +works with string-typed targets. + +See also `MenuItemExt::set_action_and_target_value` for a +description of the semantics of the action and target attributes. +## `action` +the name of the action for this item +## `format_string` +a GVariant format string + +Sets or unsets the "action" and "target" attributes of `self`. + +If `action` is `None` then both the "action" and "target" attributes +are unset (and `target_value` is ignored). + +If `action` is non-`None` then the "action" attribute is set. The +"target" attribute is then set to the value of `target_value` if it is +non-`None` 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 +`Action` and `ActionGroup` 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 `MenuItemExt::set_action_and_target` or +`MenuItemExt::set_detailed_action` for two equivalent calls that are +probably more convenient for most uses. +## `action` +the name of the action for this item +## `target_value` +a `glib::Variant` to use as the action target + +Sets or unsets an attribute on `self`. + +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-`None` then the proper position parameters +are collected to create a `glib::Variant` instance to use as the attribute +value. If it is `None` then the positional parameterrs are ignored +and the named attribute is unset. + +See also `MenuItemExt::set_attribute_value` for an equivalent call +that directly accepts a `glib::Variant`. +## `attribute` +the attribute to set +## `format_string` +a `glib::Variant` format string, or `None` + +Sets or unsets an attribute on `self`. + +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-`None` then it is used as the new value for the +attribute. If `value` is `None` then the attribute is unset. If +the `value` `glib::Variant` is floating, it is consumed. + +See also `MenuItemExt::set_attribute` for a more convenient way to do +the same. +## `attribute` +the attribute to set +## `value` +a `glib::Variant` to use as the value, or `None` + +Sets the "action" and possibly the "target" attribute of `self`. + +The format of `detailed_action` is the same format parsed by +`Action::parse_detailed_name`. + +See `MenuItemExt::set_action_and_target` or +`MenuItemExt::set_action_and_target_value` for more flexible (but +slightly less convenient) alternatives. + +See also `MenuItemExt::set_action_and_target_value` for a description of +the semantics of the action and target attributes. +## `detailed_action` +the "detailed" action string + +Sets (or unsets) the icon on `self`. + +This call is the same as calling `Icon::serialize` and using the +result as the value to `MenuItemExt::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 `None` then the icon is unset. + +Feature: `v2_38` + +## `icon` +a `Icon`, or `None` + +Sets or unsets the "label" attribute of `self`. + +If `label` is non-`None` it is used as the label for the menu item. If +it is `None` then the label attribute is unset. +## `label` +the label to set, or `None` to unset + +Creates a link from `self` to `model` if non-`None`, 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. +## `link` +type of link to establish or unset +## `model` +the `MenuModel` to link to (or `None` to unset) + +Sets or unsets the "section" link of `self` 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 `self` is added to. See `MenuItem::new_section` +for more information about what it means for a menu item to be a +section. +## `section` +a `MenuModel`, or `None` + +Sets or unsets the "submenu" link of `self` to `submenu`. + +If `submenu` is non-`None`, it is linked to. If it is `None` then the +link is unset. + +The effect of having one menu appear as a submenu of another is +exactly as it sounds. +## `submenu` +a `MenuModel`, or `None` + +`MenuLinkIter` is an opaque structure type. You must access it using +the functions below. + +# Implements + +[`MenuLinkIterExt`](trait.MenuLinkIterExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `MenuLinkIter` methods. + +# Implementors + +[`MenuLinkIter`](struct.MenuLinkIter.html) + +Gets the name of the link at the current iterator position. + +The iterator is not advanced. + +# Returns + +the type of the link + +This function combines `MenuLinkIterExt::next` with +`MenuLinkIterExt::get_name` and `MenuLinkIterExt::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 `MenuModel` +of the link that has just been advanced to. At this point, +`MenuLinkIterExt::get_name` and `MenuLinkIterExt::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 `gobject::ObjectExt::unref` when it is no longer in use. +## `out_link` +the name of the link +## `value` +the linked `MenuModel` + +# Returns + +`true` on success, or `false` if there is no additional link + +Gets the linked `MenuModel` at the current iterator position. + +The iterator is not advanced. + +# Returns + +the `MenuModel` that is linked to + +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). + +# Returns + +`true` on success, or `false` when there are no more links + +`MenuModel` 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 `MenuModel` is hierarchical: +sections and submenus are again represented by `GMenuModels`. +Menus themselves do not define their own roles. Rather, the role +of a particular `MenuModel` 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 +`ActionGroup` and `MenuModel`. The client-side counterparts to +make use of the exported information are `DBusActionGroup` and +`DBusMenuModel`. + +The API of `MenuModel` is very generic, with iterators for the +attributes and links of an item, see `MenuModelExt::iterate_item_attributes` +and `MenuModelExt::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 `MenuModel` 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. + +# Implements + +[`MenuModelExt`](trait.MenuModelExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `MenuModel` methods. + +# Implementors + +[`MenuModel`](struct.MenuModel.html), [`Menu`](struct.Menu.html) + +Queries item at position `item_index` in `self` for the attribute +specified by `attribute`. + +If the attribute exists and matches the `glib::VariantType` 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 `MenuModelExt::get_item_attribute_value` and +`glib::Variant::get`, followed by a `glib::Variant::unref`. As such, +`format_string` must make a complete copy of the data (since the +`glib::Variant` may go away after the call to `glib::Variant::unref`). In +particular, no '&' characters are allowed in `format_string`. +## `item_index` +the index of the item +## `attribute` +the attribute to query +## `format_string` +a `glib::Variant` format string + +# Returns + +`true` if the named attribute was found with the expected + type + +Queries the item at position `item_index` in `self` for the attribute +specified by `attribute`. + +If `expected_type` is non-`None` then it specifies the expected type of +the attribute. If it is `None` 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 `None` is returned. +## `item_index` +the index of the item +## `attribute` +the attribute to query +## `expected_type` +the expected type of the attribute, or + `None` + +# Returns + +the value of the attribute + +Queries the item at position `item_index` in `self` for the link +specified by `link`. + +If the link exists, the linked `MenuModel` is returned. If the link +does not exist, `None` is returned. +## `item_index` +the index of the item +## `link` +the link to query + +# Returns + +the linked `MenuModel`, or `None` + +Query the number of items in `self`. + +# Returns + +the number of items + +Queries if `self` is mutable. + +An immutable `MenuModel` will never emit the `MenuModel::items-changed` +signal. Consumers of the model may make optimisations accordingly. + +# Returns + +`true` if the model is mutable (ie: "items-changed" may be + emitted). + +Requests emission of the `MenuModel::items-changed` signal on `self`. + +This function should never be called except by `MenuModel` +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 +`MenuModel` API. Said another way: the menu must not change while +user code is running without returning to the mainloop. +## `position` +the position of the change +## `removed` +the number of items removed +## `added` +the number of items added + +Creates a `MenuAttributeIter` to iterate over the attributes of +the item at position `item_index` in `self`. + +You must free the iterator with `gobject::ObjectExt::unref` when you are done. +## `item_index` +the index of the item + +# Returns + +a new `MenuAttributeIter` + +Creates a `MenuLinkIter` to iterate over the links of the item at +position `item_index` in `self`. + +You must free the iterator with `gobject::ObjectExt::unref` when you are done. +## `item_index` +the index of the item + +# Returns + +a new `MenuLinkIter` + +`Notification` 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 `Notification` and other similar APIs is +that, if supported by the desktop environment, notifications sent +with `Notification` 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 `Notification` should be able to be +started as a D-Bus service, using `Application`. + +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 `ApplicationExt::send_notification`. + +Feature: `v2_40` + +# Implements + +[`NotificationExt`](trait.NotificationExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Notification` methods. + +Feature: `v2_40` + +# Implementors + +[`Notification`](struct.Notification.html) + +Creates a new `Notification` with `title` as its title. + +After populating `notification` with more details, it can be sent to +the desktop shell with `ApplicationExt::send_notification`. Changing +any properties after this call will not have any effect until +resending `notification`. + +Feature: `v2_40` + +## `title` +the title of the notification + +# Returns + +a new `Notification` instance + +Adds a button to `self` 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 `Action::parse_detailed_name` for a description of the format +for `detailed_action`. + +Feature: `v2_40` + +## `label` +label of the button +## `detailed_action` +a detailed action name + +Adds a button to `self` 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 `glib::Variant` instance, similar to +`glib::Variant::new`. `action` will be activated with that `glib::Variant` as its +parameter. + +Feature: `v2_40` + +## `label` +label of the button +## `action` +an action name +## `target_format` +a `glib::Variant` format string, or `None` + +Adds a button to `self` that activates `action` when clicked. +`action` must be an application-wide action (it must start with "app."). + +If `target` is non-`None`, `action` will be activated with `target` as +its parameter. + +Feature: `v2_40` + +## `label` +label of the button +## `action` +an action name +## `target` +a `glib::Variant` to use as `action`'s parameter, or `None` + +Sets the body of `self` to `body`. + +Feature: `v2_40` + +## `body` +the new body for `self`, or `None` + +Sets the default action of `self` 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 `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. + +Feature: `v2_40` + +## `detailed_action` +a detailed action name + +Sets the default action of `self` 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 `glib::Variant` instance, similar to +`glib::Variant::new`. `action` will be activated with that `glib::Variant` as its +parameter. + +When no default action is set, the application that the notification +was sent on is activated. + +Feature: `v2_40` + +## `action` +an action name +## `target_format` +a `glib::Variant` format string, or `None` + +Sets the default action of `self` 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-`None`, `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. + +Feature: `v2_40` + +## `action` +an action name +## `target` +a `glib::Variant` to use as `action`'s parameter, or `None` + +Sets the icon of `self` to `icon`. + +Feature: `v2_40` + +## `icon` +the icon to be shown in `self`, as a `Icon` + +Sets the priority of `self` to `priority`. See +`NotificationPriority` for possible values. + +Feature: `v2_42` + +## `priority` +a `NotificationPriority` + +Sets the title of `self` to `title`. + +Feature: `v2_40` + +## `title` +the new title for `self` + +Deprecated in favor of `NotificationExt::set_priority`. + +Feature: `v2_40` + +## `urgent` +`true` if `self` 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) + +Feature: `v2_42` + + +A `Permission` 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 `Permission` might represent the ability for the +user to write to a `Settings` object. This `Permission` 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. + +# Implements + +[`PermissionExt`](trait.PermissionExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Permission` methods. + +# Implementors + +[`Permission`](struct.Permission.html), [`SimplePermission`](struct.SimplePermission.html) + +Attempts to acquire the permission represented by `self`. + +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 `PermissionExt::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 `PermissionExt::acquire_async` for +the non-blocking version. +## `cancellable` +a `Cancellable`, or `None` + +# Returns + +`true` if the permission was successfully acquired + +Attempts to acquire the permission represented by `self`. + +This is the first half of the asynchronous version of +`PermissionExt::acquire`. +## `cancellable` +a `Cancellable`, or `None` +## `callback` +the `GAsyncReadyCallback` to call when done +## `user_data` +the user data to pass to `callback` + +Collects the result of attempting to acquire the permission +represented by `self`. + +This is the second half of the asynchronous version of +`PermissionExt::acquire`. +## `result` +the `AsyncResult` given to the `GAsyncReadyCallback` + +# Returns + +`true` if the permission was successfully acquired + +Gets the value of the 'allowed' property. This property is `true` if +the caller currently has permission to perform the action that +`self` represents the permission to perform. + +# Returns + +the value of the 'allowed' property + +Gets the value of the 'can-acquire' property. This property is `true` +if it is generally possible to acquire the permission by calling +`PermissionExt::acquire`. + +# Returns + +the value of the 'can-acquire' property + +Gets the value of the 'can-release' property. This property is `true` +if it is generally possible to release the permission by calling +`PermissionExt::release`. + +# Returns + +the value of the 'can-release' property + +This function is called by the `Permission` implementation to update +the properties of the permission. You should never call this +function except from a `Permission` implementation. + +GObject notify signals are generated, as appropriate. +## `allowed` +the new value for the 'allowed' property +## `can_acquire` +the new value for the 'can-acquire' property +## `can_release` +the new value for the 'can-release' property + +Attempts to release the permission represented by `self`. + +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 `PermissionExt::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 `PermissionExt::release_async` for +the non-blocking version. +## `cancellable` +a `Cancellable`, or `None` + +# Returns + +`true` if the permission was successfully released + +Attempts to release the permission represented by `self`. + +This is the first half of the asynchronous version of +`PermissionExt::release`. +## `cancellable` +a `Cancellable`, or `None` +## `callback` +the `GAsyncReadyCallback` to call when done +## `user_data` +the user data to pass to `callback` + +Collects the result of attempting to release the permission +represented by `self`. + +This is the second half of the asynchronous version of +`PermissionExt::release`. +## `result` +the `AsyncResult` given to the `GAsyncReadyCallback` + +# Returns + +`true` if the permission was successfully released + +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 `Resource` 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 if 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 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: + +```text + + + + data/splashscreen.png + dialog.ui + menumarkup.xml + + +``` + +This will create a resource bundle with the following files: + +```text +/org/gtk/Example/data/splashscreen.png +/org/gtk/Example/dialog.ui +/org/gtk/Example/menumarkup.xml +``` + +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 `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 `Resource` object. The register and unregister functions +register the resource so its files can be accessed using +`g_resources_lookup_data`. + +Once a `Resource` 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 `File` to access +the resource data. + +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 `Resource` on startup +or library load time. If you pass --manual-register two functions to register/unregister the resource is instead +created. This requires an explicit initialization call in your application/library, but it works on all platforms, +even on the minor ones where this is not available. (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 +is 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 colon-separated list of substitutions to perform +during resource lookups. + +A substitution has the form + + +```text + /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`. +## `data` +A `glib::Bytes` + +# Returns + +a new `Resource`, or `None` on error + +Returns all the names of children at the specified `path` in the resource. +The return result is a `None` terminated list of strings which should +be released with `g_strfreev`. + +If `path` is invalid or does not exist in the `Resource`, +`ResourceError::NotFound` will be returned. + +`lookup_flags` controls the behaviour of the lookup. +## `path` +A pathname inside the resource +## `lookup_flags` +A `ResourceLookupFlags` + +# Returns + +an array of constant strings + +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. +## `path` +A pathname inside the resource +## `lookup_flags` +A `ResourceLookupFlags` +## `size` +a location to place the length of the contents of the file, + or `None` if the length is not needed +## `flags` +a location to place the flags about the file, + or `None` if the length is not needed + +# Returns + +`true` if the file was found. `false` if there were errors + +Looks for a file at the specified `path` in the resource and +returns a `glib::Bytes` that lets you directly access the data in +memory. + +The data is always followed by a zero byte, so you +can safely use the data as a C string. However, that byte +is not included in the size of the 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. +## `path` +A pathname inside the resource +## `lookup_flags` +A `ResourceLookupFlags` + +# Returns + +`glib::Bytes` or `None` on error. + Free the returned object with `glib::Bytes::unref` + +Looks for a file at the specified `path` in the resource and +returns a `InputStream` that lets you read the data. + +`lookup_flags` controls the behaviour of the lookup. +## `path` +A pathname inside the resource +## `lookup_flags` +A `ResourceLookupFlags` + +# Returns + +`InputStream` or `None` on error. + Free the returned object with `gobject::ObjectExt::unref` + +Atomically increments the reference count of `self` by one. This +function is MT-safe and may be called from any thread. + +# Returns + +The passed in `Resource` + +Atomically decrements the reference count of `self` 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. + +Loads a binary resource bundle and creates a `Resource` representation of it, allowing +you to query it for data. + +If you want to use this resource in the global resource namespace you need +to register it with `g_resources_register`. +## `filename` +the path of a filename to load, in the GLib filename encoding + +# Returns + +a new `Resource`, or `None` on error + +An error code used with `G_RESOURCE_ERROR` in a `glib::Error` returned +from a `Resource` routine. + +no file was found at the requested path + +unknown error + +The `Settings` class provides a convenient API for storing and retrieving +application settings. + +Reads and writes can be considered to be non-blocking. Reading +settings with `Settings` is typically extremely fast: on +approximately the same order of magnitude (but slower than) a +`glib::HashTable` lookup. Writing settings is also extremely fast in terms +of time to return to your application, but can be extremely expensive +for other threads and other processes. Many settings backends +(including dconf) have lazy initialisation which means in the common +case of the user using their computer without modifying any settings +a lot of work can be avoided. For dconf, the D-Bus service doesn't +even need to be started in this case. For this reason, you should +only ever modify `Settings` 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 `SettingsExt::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 as 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 `glib::Variant`, and allows any `glib::VariantType` for keys. Key names +are restricted to lowercase characters, numbers and '-'. Furthermore, +the names must begin with a lowercase character, must not end +with a '-', and must not contain consecutive dashes. + +Similar to GConf, the default values in GSettings schemas can be +localized, but the localized values are stored in gettext catalogs +and looked up with the domain that is specified in the +`gettext-domain` attribute of the `` or `` +elements and the category that is specified in the `l10n` attribute of +the `` element. The string which is translated includes all text in +the `` 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 `` 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 `` element to disambiguate multiple +defaults which use the same string. + +For example: + +```text + + ['bad', 'words'] +``` + +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 `` 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 `glib::Variant` types, keys can have types that have +enumerated types. These can be described by a ``, +`` or `` element, as seen in the +[example][schema-enumerated]. The underlying type of such a key +is string, but you can use `SettingsExt::get_enum`, `SettingsExt::set_enum`, +`SettingsExt::get_flags`, `SettingsExt::set_flags` access the numeric values +corresponding to the string value of enum and flags keys. + +An example for default value: + +```text + + + + + "Hello, earthlings" + A greeting + + Greeting of the invading martians + + + + + (20,30) + + + + +``` + +An example for ranges, choices and enumerated types: + +```text + + + + + + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 'Joe' + + + + 'first' + + + + ["flag1","flag2"] + + + +``` + +## 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: + +```text + [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::Object` properties +directly to settings, using `SettingsExt::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 +`SettingsBindFlags::NoSensitivity` flag. + +## Relocatable schemas # {`gsettings`-relocatable} + +A relocatable schema is one with no `path` attribute specified on its +`` element. By using `Settings::new_with_path`, a `Settings` object +can be instantiated for a relocatable schema, assigning a path to the +instance. Paths passed to `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 `` elements in the parent schema, e.g.: + +```text + + + +``` + +## 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`: + +```text +GLIB_GSETTINGS +``` + +In the appropriate `Makefile.am`, use the following snippet to compile and +install the named schema: + +```text +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): + +```text +data/org.foo.MyApp.gschema.xml +``` + +Alternatively, if intltool 0.50.1 is in use: + +```text +[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml +``` + +GSettings will use gettext to look up translations for the `` and +`` elements, and also any `` 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 `` 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`: + +```text +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`. + +# Implements + +[`SettingsExt`](trait.SettingsExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Settings` methods. + +# Implementors + +[`Settings`](struct.Settings.html) + +Creates a new `Settings` object with the schema specified by +`schema_id`. + +Signals on the newly created `Settings` object will be dispatched +via the thread-default `glib::MainContext` in effect at the time of the +call to `Settings::new`. The new `Settings` will hold a reference +on the context. See `glib::MainContext::push_thread_default`. +## `schema_id` +the id of the schema + +# Returns + +a new `Settings` object + +Creates a new `Settings` object with a given schema, backend and +path. + +It should be extremely rare that you ever want to use this function. +It is made available for advanced use-cases (such as plugin systems +that want to provide access to schemas loaded from custom locations, +etc). + +At the most basic level, a `Settings` object is a pure composition of +4 things: a `SettingsSchema`, a `SettingsBackend`, a path within that +backend, and a `glib::MainContext` to which signals are dispatched. + +This constructor therefore gives you full control over constructing +`Settings` instances. The first 3 parameters are given directly as +`schema`, `backend` and `path`, and the main context is taken from the +thread-default (as per `Settings::new`). + +If `backend` is `None` then the default backend is used. + +If `path` is `None` then the path from the schema is used. It is an +error if `path` is `None` and the schema has no path of its own or if +`path` is non-`None` and not equal to the path that the schema does +have. +## `schema` +a `SettingsSchema` +## `backend` +a `SettingsBackend` +## `path` +the path to use + +# Returns + +a new `Settings` object + +Creates a new `Settings` object with the schema specified by +`schema_id` and a given `SettingsBackend`. + +Creating a `Settings` object with a different backend allows accessing +settings from a database other than the usual one. For example, it may make +sense to pass a backend corresponding to the "defaults" settings database on +the system to get a settings object that modifies the system default +settings instead of the settings for this user. +## `schema_id` +the id of the schema +## `backend` +the `SettingsBackend` to use + +# Returns + +a new `Settings` object + +Creates a new `Settings` object with the schema specified by +`schema_id` and a given `SettingsBackend` and path. + +This is a mix of `Settings::new_with_backend` and +`Settings::new_with_path`. +## `schema_id` +the id of the schema +## `backend` +the `SettingsBackend` to use +## `path` +the path to use + +# Returns + +a new `Settings` object + +Creates a new `Settings` object with the relocatable schema specified +by `schema_id` and a given path. + +You only need to do this if you want to directly create a settings +object with a schema that doesn't have a specified path of its own. +That's quite rare. + +It is a programmer error to call this function for a schema that +has an explicitly specified path. + +It is a programmer error if `path` is not a valid path. A valid path +begins and ends with '/' and does not contain two consecutive '/' +characters. +## `schema_id` +the id of the schema +## `path` +the path to use + +# Returns + +a new `Settings` object + + + +# Deprecated since 2.40 + +Use `SettingsSchemaSource::list_schemas` instead + +# Returns + +a list of relocatable + `Settings` schemas that are available. The list must not be + modified or freed. + + + +# Deprecated since 2.40 + +Use `SettingsSchemaSource::list_schemas` instead. +If you used `Settings::list_schemas` to check for the presence of +a particular schema, use `SettingsSchemaSource::lookup` instead +of your whole loop. + +# Returns + +a list of `Settings` + schemas that are available. The list must not be modified or + freed. + +Ensures that all pending operations for the given are complete for +the default backend. + +Writes made to a `Settings` are handled asynchronously. For this +reason, it is very unlikely that the changes have it to disk by the +time `SettingsExt::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. +## `object` +the object +## `property` +the property whose binding is removed + +Applies any changes that have been made to the settings. This +function does nothing unless `self` is in 'delay-apply' mode; +see `SettingsExt::delay`. In the normal case settings are always +applied immediately. + +Create a binding between the `key` in the `self` 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 `SettingsExt::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 `SettingsBindFlags::NoSensitivity`, 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 `SettingsExt::bind_writable` +for more details about writable bindings. + +Note that the lifecycle of the binding is tied to the 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. +## `key` +the key to bind +## `object` +a `gobject::Object` +## `property` +the name of the property to bind +## `flags` +flags for the binding + +Create a binding between the `key` in the `self` 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 the 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. +## `key` +the key to bind +## `object` +a `gobject::Object` +## `property` +the name of the property to bind +## `flags` +flags for the binding +## `get_mapping` +a function that gets called to convert values + from `self` to `object`, or `None` to use the default GIO mapping +## `set_mapping` +a function that gets called to convert values + from `object` to `self`, or `None` to use the default GIO mapping +## `user_data` +data that gets passed to `get_mapping` and `set_mapping` +## `destroy` +`GDestroyNotify` function for `user_data` + +Create a binding between the writability of `key` in the +`self` 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 the 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. +## `key` +the key to bind +## `object` +a `gobject::Object` +## `property` +the name of a boolean property to bind +## `inverted` +whether to 'invert' the value + +Creates a `Action` corresponding to a given `Settings` key. + +The action has the same name as the key. + +The value of the key becomes the state of the action and the action +is enabled when the key is writable. Changing the state of the +action results in the key being written to. Changes to the value or +writability of the key cause appropriate change notifications to be +emitted for the action. + +For boolean-valued keys, action activations take no parameter and +result in the toggling of the value. For all other types, +activations take the new value for the key (which must have the +correct type). +## `key` +the name of a key in `self` + +# Returns + +a new `Action` + +Changes the `Settings` object into 'delay-apply' mode. In this +mode, changes to `self` are not immediately propagated to the +backend, but kept locally until `SettingsExt::apply` is called. + +Gets the value that is stored at `key` in `self`. + +A convenience function that combines `SettingsExt::get_value` with +`glib::Variant::get`. + +It is a programmer error to give a `key` that isn't contained in the +schema for `self` or for the `glib::VariantType` of `format` to mismatch +the type given in the schema. +## `key` +the key to get the value for +## `format` +a `glib::Variant` format string + +Gets the value that is stored at `key` in `self`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the key to get the value for + +# Returns + +a boolean + +Creates a child settings object which has a base path of +`base-path/@name`, where `base-path` is the base path of +`self`. + +The schema for the child settings object must have been declared +in the schema of `self` using a `` element. +## `name` +the name of the child schema + +# Returns + +a 'child' settings object + +Gets the "default value" of a key. + +This is the value that would be read if `SettingsExt::reset` were to be +called on the key. + +Note that this may be a different value than returned by +`SettingsSchemaKey::get_default_value` if the system administrator +has provided a default value. + +Comparing the return values of `SettingsExt::get_default_value` and +`SettingsExt::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 `self`. + +Feature: `v2_40` + +## `key` +the key to get the default value for + +# Returns + +the default value + +Gets the value that is stored at `key` in `self`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the key to get the value for + +# Returns + +a double + +Gets the value that is stored in `self` 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 `self` 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. +## `key` +the key to get the value for + +# Returns + +the enum value + +Gets the value that is stored in `self` 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 `self` 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. +## `key` +the key to get the value for + +# Returns + +the flags value + +Returns whether the `Settings` object has any unapplied +changes. This can only be the case if it is in 'delayed-apply' mode. + +# Returns + +`true` if `self` has unapplied changes + +Gets the value that is stored at `key` in `self`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the key to get the value for + +# Returns + +an integer + +Gets the value that is stored at `key` in `self`. + +A convenience variant of `SettingsExt::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 `self`. + +Feature: `v2_50` + +## `key` +the key to get the value for + +# Returns + +a 64-bit integer + +Gets the value that is stored at `key` in `self`, 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 `None` 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 `None`. The same pointer is given +to each invocation of `mapping`. The final value of that `gpointer` is +what is returned by this function. `None` is valid; it is returned +just as any other value would be. +## `key` +the key to get the value for +## `mapping` +the function to map the value in the + settings database to the value used by the application +## `user_data` +user data for `mapping` + +# Returns + +the result, which may be `None` + +Queries the range of a key. + +# Deprecated since 2.40 + +Use `SettingsSchemaKey::get_range` instead. +## `key` +the key to query the range of + +Gets the value that is stored at `key` in `self`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the key to get the value for + +# Returns + +a newly-allocated string + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the key to get the value for + +# Returns + +a +newly-allocated, `None`-terminated array of strings, the value that +is stored at `key` in `self`. + +Gets the value that is stored at `key` in `self`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the key to get the value for + +# Returns + +an unsigned integer + +Gets the value that is stored at `key` in `self`. + +A convenience variant of `SettingsExt::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 `self`. + +Feature: `v2_50` + +## `key` +the key to get the value for + +# Returns + +a 64-bit unsigned integer + +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 `SettingsExt::reset` this function should always return +`None` (assuming something is not wrong with the system +configuration). + +It is possible that `SettingsExt::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 `self`. + +Feature: `v2_40` + +## `key` +the key to get the user value for + +# Returns + +the user's value, if set + +Gets the value that is stored in `self` for `key`. + +It is a programmer error to give a `key` that isn't contained in the +schema for `self`. +## `key` +the key to get the value for + +# Returns + +a new `glib::Variant` + +Finds out if a key can be written or not +## `name` +the name of a key + +# Returns + +`true` if the key `name` is writable + +Gets the list of children on `self`. + +The list is exactly the list of strings for which it is not an error +to call `SettingsExt::get_child`. + +For GSettings objects that are lists, this value can change at any +time and you should connect to the "children-changed" signal to watch +for those changes. Note that there is a race condition here: you may +request a child after listing it only for it to have been destroyed +in the meantime. For this reason, `SettingsExt::get_child` may return +`None` even for a child that was listed by this function. + +For GSettings objects that are not lists, you should probably not be +calling 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. + +# Returns + +a list of the children on `self` + +Introspects the list of keys on `self`. + +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. + +# Returns + +a list of the keys on `self` + +Checks if the given `value` is of the correct type and within the +permitted range for `key`. + +# Deprecated since 2.40 + +Use `SettingsSchemaKey::range_check` instead. +## `key` +the key to check +## `value` +the value to check + +# Returns + +`true` if `value` is valid for `key` + +Resets `key` to its default value. + +This call resets the key, as much as possible, to its default value. +That might the value specified in the schema or the one set by the +administrator. +## `key` +the name of a key + +Reverts all non-applied changes to the settings. This function +does nothing unless `self` is in 'delay-apply' mode; see +`SettingsExt::delay`. In the normal case settings are always applied +immediately. + +Change notifications will be emitted for affected keys. + +Sets `key` in `self` to `value`. + +A convenience function that combines `SettingsExt::set_value` with +`glib::Variant::new`. + +It is a programmer error to give a `key` that isn't contained in the +schema for `self` or for the `glib::VariantType` of `format` to mismatch +the type given in the schema. +## `key` +the name of the key to set +## `format` +a `glib::Variant` format string + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Sets `key` in `self` to `value`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the name of the key to set +## `value` +the value to set it to + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Sets `key` in `self` to `value`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the name of the key to set +## `value` +the value to set it to + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Looks up the enumerated type nick for `value` and writes it to `key`, +within `self`. + +It is a programmer error to give a `key` that isn't contained in the +schema for `self` 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 +`SettingsExt::get_string` will return the 'nick' associated with +`value`. +## `key` +a key, within `self` +## `value` +an enumerated value + +# Returns + +`true`, if the set succeeds + +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 +`self`. + +It is a programmer error to give a `key` that isn't contained in the +schema for `self` 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 +`SettingsExt::get_strv` will return an array of 'nicks'; one for each +bit in `value`. +## `key` +a key, within `self` +## `value` +a flags value + +# Returns + +`true`, if the set succeeds + +Sets `key` in `self` to `value`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the name of the key to set +## `value` +the value to set it to + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Sets `key` in `self` to `value`. + +A convenience variant of `SettingsExt::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 `self`. + +Feature: `v2_50` + +## `key` +the name of the key to set +## `value` +the value to set it to + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Sets `key` in `self` to `value`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the name of the key to set +## `value` +the value to set it to + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Sets `key` in `self` to `value`. + +A convenience variant of `SettingsExt::set` for string arrays. If +`value` is `None`, 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 `self`. +## `key` +the name of the key to set +## `value` +the value to set it to, or `None` + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Sets `key` in `self` to `value`. + +A convenience variant of `SettingsExt::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 `self`. +## `key` +the name of the key to set +## `value` +the value to set it to + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Sets `key` in `self` to `value`. + +A convenience variant of `SettingsExt::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 `self`. + +Feature: `v2_50` + +## `key` +the name of the key to set +## `value` +the value to set it to + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +Sets `key` in `self` to `value`. + +It is a programmer error to give a `key` that isn't contained in the +schema for `self` or for `value` to have the incorrect type, per +the schema. + +If `value` is floating then this function consumes the reference. +## `key` +the name of the key to set +## `value` +a `glib::Variant` of the correct type + +# Returns + +`true` if setting the key succeeded, + `false` if the key was not writable + +A `SimpleAction` is the obvious simple implementation of the `Action` +interface. This is the easiest way to create an action for purposes of +adding it to a `SimpleActionGroup`. + +See also ``GtkAction``. + +# Implements + +[`SimpleActionExt`](trait.SimpleActionExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionExt`](trait.ActionExt.html) + +Trait containing all `SimpleAction` methods. + +# Implementors + +[`SimpleAction`](struct.SimpleAction.html) + +Creates a new action. + +The created action is stateless. See `SimpleAction::new_stateful`. +## `name` +the name of the action +## `parameter_type` +the type of parameter to the activate function + +# Returns + +a new `SimpleAction` + +Creates a new stateful action. + +`state` is the initial state of the action. All future state values +must have the same `glib::VariantType` as the initial state. + +If the `state` GVariant is floating, it is consumed. +## `name` +the name of the action +## `parameter_type` +the type of the parameter to the activate function +## `state` +the initial state of the action + +# Returns + +a new `SimpleAction` + +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. +## `enabled` +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 `Action::change_state` to +request the change. + +If the `value` GVariant is floating, it is consumed. +## `value` +the new `glib::Variant` for the state + +Sets the state hint for the action. + +See `Action::get_state_hint` for more information about +action state hints. + +Feature: `v2_44` + +## `state_hint` +a `glib::Variant` representing the state hint + +`SimpleActionGroup` is a hash table filled with `Action` objects, +implementing the `ActionGroup` and `ActionMap` interfaces. + +# Implements + +[`SimpleActionGroupExt`](trait.SimpleActionGroupExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html), [`ActionMapExt`](trait.ActionMapExt.html) + +Trait containing all `SimpleActionGroup` methods. + +# Implementors + +[`SimpleActionGroup`](struct.SimpleActionGroup.html) + +Creates a new, empty, `SimpleActionGroup`. + +# Returns + +a new `SimpleActionGroup` + +A convenience function for creating multiple `SimpleAction` instances +and adding them to the action group. + +# Deprecated since 2.38 + +Use `ActionMap::add_action_entries` +## `entries` +a pointer to the first item in + an array of `ActionEntry` structs +## `n_entries` +the length of `entries`, or -1 +## `user_data` +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`. + +# Deprecated since 2.38 + +Use `ActionMap::add_action` +## `action` +a `Action` + +Looks up the action with the name `action_name` in the group. + +If no such action exists, returns `None`. + +# Deprecated since 2.38 + +Use `ActionMap::lookup_action` +## `action_name` +the name of an action + +# Returns + +a `Action`, or `None` + +Removes the named action from the action group. + +If no action of this name is in the group then nothing happens. + +# Deprecated since 2.38 + +Use `ActionMap::remove_action` +## `action_name` +the name of the action + +`SimplePermission` is a trivial implementation of `Permission` 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. + +# Implements + +[`PermissionExt`](trait.PermissionExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Creates a new `Permission` instance that represents an action that is +either always or never allowed. +## `allowed` +`true` if the action is allowed + +# Returns + +the `SimplePermission`, as a `Permission` + +`ThemedIcon` is an implementation of `Icon` that supports icon themes. +`ThemedIcon` contains a list of all of the icons present in an icon +theme, so that icons can be looked up quickly. `ThemedIcon` 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. + +# Implements + +[`ThemedIconExt`](trait.ThemedIconExt.html), [`ObjectExt`](trait.ObjectExt.html), [`IconExt`](trait.IconExt.html) + +Trait containing all `ThemedIcon` methods. + +# Implementors + +[`ThemedIcon`](struct.ThemedIcon.html) + +Creates a new themed icon for `iconname`. +## `iconname` +a string containing an icon name. + +# Returns + +a new `ThemedIcon`. + +Creates a new themed icon for `iconnames`. +## `iconnames` +an array of strings containing icon names. +## `len` +the length of the `iconnames` array, or -1 if `iconnames` is + `None`-terminated + +# Returns + +a new `ThemedIcon` + +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: + +```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"); +``` +## `iconname` +a string containing an icon name + +# Returns + +a new `ThemedIcon`. + +Append a name to the list of icons from within `self`. + +Note that doing so invalidates the hash computed by prior calls +to `Icon::hash`. +## `iconname` +name of icon to append to list of icons from within `self`. + +Gets the names of icons from within `self`. + +# Returns + +a list of icon names. + +Prepend a name to the list of icons from within `self`. + +Note that doing so invalidates the hash computed by prior calls +to `Icon::hash`. +## `iconname` +name of icon to prepend to list of icons from within `self`. + +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 +`TlsServerConnection`). + +# Implements + +[`TlsCertificateExt`](trait.TlsCertificateExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `TlsCertificate` methods. + +# Implementors + +[`TlsCertificate`](struct.TlsCertificate.html) + +Creates a `TlsCertificate` 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 `TlsCertificate: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 `None` and +set `error`. Otherwise, this behaves like +`TlsCertificate::new_from_pem`. +## `file` +file containing a PEM-encoded certificate to import + +# Returns + +the new certificate, or `None` on error + +Creates a `TlsCertificate` 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 +`TlsCertificate: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 +`None` and set `error`. Otherwise, this behaves like +`TlsCertificate::new_from_pem`. +## `cert_file` +file containing one or more PEM-encoded + certificates to import +## `key_file` +file containing a PEM-encoded private key + to import + +# Returns + +the new certificate, or `None` on error + +Creates a `TlsCertificate` 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 `TlsCertificate: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 `TlsCertificate: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. +## `data` +PEM-encoded certificate data +## `length` +the length of `data`, or -1 if it's 0-terminated. + +# Returns + +the new certificate, or `None` if `data` is invalid + +Creates one or more `GTlsCertificates` from the PEM-encoded +data in `file`. If `file` cannot be read or parsed, the function will +return `None` and set `error`. If `file` does not contain any +PEM-encoded certificates, this will return an empty list and not +set `error`. +## `file` +file containing PEM-encoded certificates to import + +# Returns + +a +`glib::List` containing `TlsCertificate` objects. You must free the list +and its contents when you are done with it. + +Gets the `TlsCertificate` representing `self`'s issuer, if known + +# Returns + +The certificate of `self`'s issuer, +or `None` if `self` is self-signed or signed with an unknown +certificate. + +Check if two `TlsCertificate` 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 `TlsCertificate:issuer`, `TlsCertificate:private-key`, or +`TlsCertificate:private-key-pem` properties differ. + +Feature: `v2_34` + +## `cert_two` +second certificate to compare + +# Returns + +whether the same or not + +This verifies `self` and returns a set of `TlsCertificateFlags` +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 `None`, `self`'s name(s) will be compared against +it, and `TlsCertificateFlags::BadIdentity` will be set in the return +value if it does not match. If `identity` is `None`, that bit will +never be set in the return value. + +If `trusted_ca` is not `None`, then `self` (or one of the certificates +in its chain) must be signed by it, or else +`TlsCertificateFlags::UnknownCa` will be set in the return value. If +`trusted_ca` is `None`, that bit will never be set in the return +value. + +(All other `TlsCertificateFlags` values will always be set or unset +as appropriate.) +## `identity` +the expected peer identity +## `trusted_ca` +the certificate of a trusted authority + +# Returns + +the appropriate `TlsCertificateFlags` diff --git a/glib/docs.md b/glib/docs.md new file mode 100644 index 00000000..00c502b8 --- /dev/null +++ b/glib/docs.md @@ -0,0 +1,1114 @@ + + +`IMPL` Boxed wrapper implementation. + +Wrapper implementations for Boxed types. See `glib_wrapper!`. + +Memory management functions for a boxed type. + +Makes a copy. + +Frees the object. + +Encapsulates memory management logic for boxed types. + + +A shared immutable byte slice (the equivalent of `Rc<[u8]>`). + +`From` implementations that take references (e.g. `&[u8]`) copy the +data. The `from_static` constructor avoids copying static data. + +``` +use glib::Bytes; + +let v = vec![1, 2, 3]; +let b = Bytes::from(&v); +assert_eq!(v, b); + +let s = b"xyz"; +let b = Bytes::from_static(s); +assert_eq!(&s[..], b); +``` + +Copies `data` into a new shared slice. + +Creates a view into static `data` without copying. + + +Representation of an `enum` for dynamically, at runtime, querying the values of the enum and +using them. + +Create a new `EnumClass` from a `Type`. + +Returns `None` if `type_` is not representing an enum. + +`Type` of the enum. + +Gets `EnumValue` by integer `value`, if existing. + +Returns `None` if the enum does not contain any value +with `value`. + +Gets `EnumValue` by string name `name`, if existing. + +Returns `None` if the enum does not contain any value +with name `name`. + +Gets `EnumValue` by string nick `nick`, if existing. + +Returns `None` if the enum does not contain any value +with nick `nick`. + +Gets all `EnumValue` of this `EnumClass`. + +Converts integer `value` to a `Value`, if part of the enum. + +Converts string name `name` to a `Value`, if part of the enum. + +Converts string nick `nick` to a `Value`, if part of the enum. + +Representation of a single enum value of an `EnumClass`. + +Get integer value corresponding to the value. + +Get name corresponding to the value. + +Get nick corresponding to the value. + +Convert enum value to a `Value`. + +Convert enum value from a `Value`. + +Get `EnumClass` to which the enum value belongs. + +Representation of a `flags` for dynamically, at runtime, querying the values of the enum and +using them + +Create a new `FlagsClass` from a `Type` + +Returns `None` if `type_` is not representing a flags type. + +`Type` of the flags. + +Gets `FlagsValue` by integer `value`, if existing. + +Returns `None` if the flags do not contain any value +with `value`. + +Gets `FlagsValue` by string name `name`, if existing. + +Returns `None` if the flags do not contain any value +with name `name`. + +Gets `FlagsValue` by string nick `nick`, if existing. + +Returns `None` if the flags do not contain any value +with nick `nick`. + +Gets all `FlagsValue` of this `FlagsClass`. + +Converts integer `value` to a `Value`, if part of the flags. + +Converts string name `name` to a `Value`, if part of the flags. + +Converts string nick `nick` to a `Value`, if part of the flags. + +Checks if the flags corresponding to integer `f` is set in `value`. + +Checks if the flags corresponding to string name `name` is set in `value`. + +Checks if the flags corresponding to string nick `nick` is set in `value`. + +Sets flags value corresponding to integer `f` in `value`, if part of that flags. If the +flag is already set, it will succeed without doing any changes. + +Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original +value otherwise. + +Sets flags value corresponding to string name `name` in `value`, if part of that flags. +If the flag is already set, it will succeed without doing any changes. + +Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original +value otherwise. + +Sets flags value corresponding to string nick `nick` in `value`, if part of that flags. +If the flag is already set, it will succeed without doing any changes. + +Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original +value otherwise. + +Unsets flags value corresponding to integer `f` in `value`, if part of that flags. +If the flag is already unset, it will succeed without doing any changes. + +Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original +value otherwise. + +Unsets flags value corresponding to string name `name` in `value`, if part of that flags. +If the flag is already unset, it will succeed without doing any changes. + +Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original +value otherwise. + +Unsets flags value corresponding to string nick `nick` in `value`, if part of that flags. +If the flag is already unset, it will succeed without doing any changes. + +Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original +value otherwise. + +Returns a new `FlagsBuilder` for conveniently setting/unsetting flags +and building a `Value`. + +Returns a new `FlagsBuilder` for conveniently setting/unsetting flags +and building a `Value`. The `Value` is initialized with `value`. + +Representation of a single flags value of a `FlagsClass`. + +Get integer value corresponding to the value. + +Get name corresponding to the value. + +Get nick corresponding to the value. + +Convert flags value to a `Value`. + +Convert flags values from a `Value`. This returns all flags that are set. + +Get `FlagsClass` to which the flags value belongs. + +Builder for conveniently setting/unsetting flags and returning a `Value`. + +Example for getting a flags property, unsetting some flags and setting the updated flags on the +object again: + +```ignore +let flags = obj.get_property("flags").unwrap(); +let flags_class = FlagsClass::new(flags.type_()).unwrap(); +let flags = flags_class.builder_with_value(flags).unwrap() + .unset_by_nick("some-flag") + .unset_by_nick("some-other-flag") + .build() + .unwrap(); +obj.set_property("flags", &flags).unwrap(); +``` + +If setting/unsetting any value fails, `build()` returns `None`. + +Sets flags corresponding to integer value `f`. + +Sets flags corresponding to string name `name`. + +Sets flags corresponding to string nick `nick`. + +Unsets flags corresponding to integer value `f`. + +Unsets flags corresponding to string name `name`. + +Unsets flags corresponding to string nick `nick`. + +Converts to the final `Value`, unless any previous setting/unsetting of flags failed. + + +`Error` binding and helper trait. + +A generic error capable of representing various error domains (types). + +Creates an error with supplied error enum variant and message. + +Checks if the error domain matches `T`. + +Tries to convert to a specific error enum. + +Returns `Some` if the error belongs to the enum's error domain and +`None` otherwise. + +# Examples + +```ignore +if let Some(file_error) = error.kind::() { + match file_error { + FileError::Exist => ... + FileError::Isdir => ... + ... + } +} +``` + +```ignore +match error { + Some(FileError::Exist) => ... + Some(FileError::Isdir) => ... + ... +} +``` + +`GLib` error domain. + +This trait is implemented by error enums that represent error domains (types). + +Returns the quark identifying the error domain. + +As returned from `g_some_error_quark`. + +Gets the integer representation of the variant. + +Tries to convert an integer code to an enum variant. + +By convention, the `Failed` variant, if present, is a catch-all, +i.e. any unrecognized codes map to it. + +Generic error used for functions that fail without any further information + + +# **glib**, **gobject** and **gio** bindings for Rust + +This library contains + +- bindings to some essential GLib, GObject, GIO types and APIs, + +- common building blocks used in both handmade and machine generated +bindings to GTK+ and other GLib-based libraries. + +It is the foundation for higher level libraries with uniform Rusty (safe and +strongly typed) APIs. It avoids exposing GLib-specific data types where +possible and is not meant to provide comprehensive GLib bindings, which +would often amount to duplicating the Rust Standard Library or other utility +crates. + +The library is a work in progress: expect missing functionality and breaking +changes. + +# Dynamic typing + +Most types in the GLib family have type identifiers +([`Type`](types/enum.Type.html)). Their corresponding Rust types implement +the [`StaticType`](types/trait.StaticType.html) trait. + +Dynamically typed [`Value`](value/index.html) can carry values of any `T: +StaticType`. + +[`Variant`](variant/index.html) can carry values of `T: StaticVariantType`. + +# Errors + +Errors are represented by [`Error`](error/struct.Error.html), which can +carry values from various [error +domains](error/trait.ErrorDomain.html#implementors) (such as +[`FileError`](enum.FileError.html)). + +# Objects + +Each class and interface has a corresponding smart pointer struct +representing an instance of that type (e.g. `Object` for `GObject`, +`gtk::Widget` for `GtkWidget`). They are reference counted and feature +interior mutability similarly to Rust's `Rc>` idiom. +Consequently, cloning objects is cheap and their methods never require +mutable borrows. Two smart pointers are equal iff they point to the same +object. + +The root of the object hierarchy is [`Object`](object/struct.Object.html). +Inheritance and subtyping is denoted with the [`IsA`](object/trait.IsA.html) +marker trait. The [`Cast`](object/trait.Cast.html) trait enables upcasting +and downcasting. + +Interfaces and non-leaf classes also have corresponding traits (e.g. +`ObjectExt` and `gtk::WidgetExt`), which are blanketly implemented for all +their subtypes. + +# Under the hood + +GLib-based libraries largely operate on pointers to various boxed or +reference counted structures so the bindings have to implement corresponding +smart pointers (wrappers), which encapsulate resource management and safety +checks. Such wrappers are defined via the +[`glib_wrapper!`](macro.glib_wrapper!.html) macro, which uses abstractions +defined in the [`wrapper`](wrapper/index.html), [`boxed`](boxed/index.html), +[`shared`](shared/index.html) and [`object`](object/index.html) modules. + +The [`translate`](translate/index.html) module defines and partly implements +conversions between high level Rust types (including the aforementioned +wrappers) and their FFI counterparts. + + +`IMPL` Object wrapper implementation and `Object` binding. + +Upcasting and downcasting support. + +Provides conversions up and down the class hierarchy tree. + +Upcasts an object to a superclass or interface `T`. + +*NOTE*: This statically checks at compile-time if casting is possible. It is not always +known at compile-time, whether a specific object implements an interface or not, in which case +`upcast` would fail to compile. `dynamic_cast` can be used in these circumstances, which +is checking the types at runtime. + +# Example + +```ignore +let button = gtk::Button::new(); +let widget = button.upcast::(); +``` + +Tries to downcast to a subclass or interface implementor `T`. + +Returns `Ok(T)` if the object is an instance of `T` and `Err(self)` +otherwise. + +*NOTE*: This statically checks at compile-time if casting is possible. It is not always +known at compile-time, whether a specific object implements an interface or not, in which case +`upcast` would fail to compile. `dynamic_cast` can be used in these circumstances, which +is checking the types at runtime. + +# Example + +```ignore +let button = gtk::Button::new(); +let widget = button.upcast::(); +assert!(widget.downcast::().is_ok()); +``` + +Returns `true` if the object is an instance of (can be cast to) `T`. + +Tries to cast to an object of type `T`. This handles upcasting, downcasting +and casting between interface and interface implementors. All checks are performed at +runtime, while `downcast` and `upcast` will do many checks at compile-time already. + +It is not always known at compile-time, whether a specific object implements an interface or +not, and checking as to be performed at runtime. + +Returns `Ok(T)` if the object is an instance of `T` and `Err(self)` +otherwise. + +# Example + +```ignore +let button = gtk::Button::new(); +let widget = button.dynamic_cast::(); +assert!(widget.is_ok); +let widget = widget.unwrap(); +assert!(widget.dynamic_cast::().is_ok()); +``` + +Declares the "is a" relationship. + +`Self` is said to implement `T`. + +For instance, since originally `GtkWidget` is a subclass of `GObject` and +implements the `GtkBuildable` interface, `gtk::Widget` implements +`IsA` and `IsA`. + + +The trait can only be implemented if the appropriate `ToGlibPtr` +implementations exist. + +`T` always implements `IsA`. + +Downcasts support. + +Checks if it's possible to downcast to `T`. + +Returns `true` if the instance implements `T` and `false` otherwise. + +Tries to downcast to `T`. + +Returns `Ok(T)` if the instance implements `T` and `Err(Self)` otherwise. + +Downcasts to `T` unconditionally. + +Panics if compiled with `debug_assertions` and the instance doesn't implement `T`. + +Wrapper implementations for Object types. See `glib_wrapper!`. + + +Traits and essential types intended for blanket imports. + + +`IMPL` Shared (reference counted) wrapper implementation. + +Wrapper implementations for shared types. See `glib_wrapper!`. + +Encapsulates memory management logic for shared types. + + +`IMPL` Low level signal support. + +Whether to propagate the signal to the default handler. + +Don't inhibit default handlers without a reason, they're usually helpful. + + +The id of a source that is returned by `idle_add` and `timeout_add`. + +A value of 0 is a good default as it is never a valid source ID. + +Continue calling the closure in the future iterations or drop it. + +This is the return type of `idle_add` and `timeout_add` closures. + +`Continue(true)` keeps the closure assigned, to be rerun when appropriate. + +`Continue(false)` disconnects and drops it. + +Unwinding propagation guard. Aborts the process if destroyed while +panicking. + +Adds a closure to be called by the default main loop when it's idle. + +`func` will be called repeatedly until it returns `Continue(false)`. + +The default main loop almost always is the main loop of the main thread. +Thus the closure is called on the main thread. + +Adds a closure to be called by the default main loop at regular intervals +with millisecond granularity. + +`func` will be called repeatedly every `interval` milliseconds until it +returns `Continue(false)`. Precise timing is not guaranteed, the timeout may +be delayed by other events. Prefer `timeout_add_seconds` when millisecond +precision is not necessary. + +The default main loop almost always is the main loop of the main thread. +Thus the closure is called on the main thread. + +Adds a closure to be called by the default main loop at regular intervals +with second granularity. + +`func` will be called repeatedly every `interval` seconds until it +returns `Continue(false)`. Precise timing is not guaranteed, the timeout may +be delayed by other events. + +The default main loop almost always is the main loop of the main thread. +Thus the closure is called on the main thread. + +Adds a closure to be called by the main loop the returned `Source` is attached to when a child +process exits. + +`func` will be called when `pid` exits + +Adds a closure to be called by the default main loop whenever a UNIX signal is raised. + +`func` will be called repeatedly every time `signum` is raised until it +returns `Continue(false)`. + +The default main loop almost always is the main loop of the main thread. +Thus the closure is called on the main thread. + +Removes the source with the given id `source_id` from the default main context. + +It is a programmer error to attempt to remove a non-existent source. +Note: source id are reused. + +For historical reasons, the native function always returns true, so we +ignore it here. + +The priority of sources + + +Adds a closure to be called by the main loop the return `Source` is attached to when it's idle. + +`func` will be called repeatedly until it returns `Continue(false)`. + +Adds a closure to be called by the main loop the returned `Source` is attached to at regular +intervals with millisecond granularity. + +`func` will be called repeatedly every `interval` milliseconds until it +returns `Continue(false)`. Precise timing is not guaranteed, the timeout may +be delayed by other events. Prefer `timeout_add_seconds` when millisecond +precision is not necessary. + +Adds a closure to be called by the main loop the returned `Source` is attached to at regular +intervals with second granularity. + +`func` will be called repeatedly every `interval` seconds until it +returns `Continue(false)`. Precise timing is not guaranteed, the timeout may +be delayed by other events. + +Adds a closure to be called by the main loop the returned `Source` is attached to when a child +process exits. + +`func` will be called when `pid` exits + +Adds a closure to be called by the main loop the returned `Source` is attached to whenever a +UNIX signal is raised. + +`func` will be called repeatedly every time `signum` is raised until it +returns `Continue(false)`. + + +Translation between GLib/GLib-based FFI types and their Rust counterparts. + +This module allows library bindings authors to decouple type translation +logic and use unified idioms at FFI boundaries. It also implements +translation of GLib core data types. + +`FromGlib`, `from_glib` and `ToGlib` translate simple types like `bool`. + +```ignore + pub fn set_accept_focus(&self, accept_focus: bool) { + unsafe { glib_ffi::gdk_window_set_accept_focus(self.pointer, accept_focus.to_glib()) } + } + + pub fn get_accept_focus(&self) -> bool { + unsafe { from_glib(glib_ffi::gdk_window_get_accept_focus(self.pointer)) } + } +``` + +`ToGlibPtr`, `FromGlibPtrNone`, `FromGlibPtrFull` and `FromGlibPtrBorrow` work on `gpointer`s +and support different modes of ownership transfer. + +```ignore + fn get_title(&self) -> Option { + unsafe { + let title = glib_ffi::gtk_window_get_title(self.pointer); + from_glib_none(title) + } + } +``` + +Letting the foreign library borrow pointers from the Rust side often +requires having a temporary variable of an intermediate type (e.g. `CString`). +A `Stash` contains the temporary storage and a pointer into it that +is valid for the lifetime of the `Stash`. As the lifetime of the `Stash` returned +from `to_glib_none` is at least the enclosing statement, you can avoid explicitly +binding the stash in most cases and just take the pointer out of it: + +```ignore + pub fn set_icon_name(&self, name: &str) { + unsafe { + glib_ffi::gdk_window_set_icon_name(self.pointer, name.to_glib_none().0) + } + } +``` + +A pointer + +Overrides pointer mutability. + +Use when the C API should be specifying a const pointer but doesn't. + +A trait for creating an uninitialized value. Handy for receiving outparams. + +Returns an uninitialized value. + +Returns an uninitialized value. + +Returns `Some(val)` if the condition is true and `None` otherwise. + +Helper type that stores temporary values used for translation. + +`P` is the foreign type pointer and the first element of the tuple. + +`T` is the Rust type that is translated. + +The second element of the tuple is the temporary storage defined +by the implementation of `ToGlibPtr

for T` + +Say you want to pass a `*mut GdkWindowAttr` to a foreign function. The `Stash` +will own a `GdkWindowAttr` and a `CString` that `GdkWindowAttr::title` points into. + +```ignore +impl <'a> ToGlibPtr<'a, *mut glib_ffi::GdkWindowAttr> for WindowAttr { + type Storage = (Box, Stash<'a, *const c_char, Option>); + + fn to_glib_none(&'a self) -> Stash<*mut glib_ffi::GdkWindowAttr, WindowAttr> { + let title = self.title.to_glib_none(); + + let mut attrs = Box::new(glib_ffi::GdkWindowAttr { + title: title.0, + // .... + }); + + Stash(&mut *attrs, (attrs, title)) + } +} +``` + +Translate a simple type. + +Provides the default pointer type to be used in some container conversions. + +It's `*mut c_char` for `String`, `*mut GtkButton` for `gtk::Button`, etc. + +Translate to a pointer. + +Transfer: none. + +The pointer in the `Stash` is only valid for the lifetime of the `Stash`. + +Transfer: container. + +We transfer the container ownership to the foreign library retaining +the elements ownership. + +Transfer: full. + +We transfer the ownership to the foreign library. + + +Translate to a pointer with a mutable borrow. + +Transfer: none. + +The pointer in the `Stash` is only valid for the lifetime of the `Stash`. + +Translate a simple type. + +Translate a simple type. + +Translate from a pointer type without taking ownership, transfer: none. + +Translate from a pointer type taking ownership, transfer: full. + +Translate from a pointer type by borrowing. Don't increase the refcount + +Translate from a pointer type, transfer: none. + +Translate from a pointer type, transfer: full (assume ownership). + +Translate from a pointer type, borrowing the pointer. + +Translate from a container. + +Transfer: none. + +`num` is the advised number of elements. + +Transfer: container. + +`num` is the advised number of elements. + +Transfer: full. + +`num` is the advised number of elements. + +Translate from a container of pointers. + +Transfer: none. + +Transfer: container. + +Transfer: full. + + +Runtime type information. + +A GLib or GLib-based library type + +An invalid `Type` used as error return value in some functions + +The fundamental type corresponding to the unit type `()` + +The fundamental type corresponding to `i8` + +The fundamental type corresponding to `u8` + +The fundamental type corresponding to `bool` + +The fundamental type corresponding to `i32` + +The fundamental type corresponding to `u32` + +The fundamental type corresponding to C `long` + +The fundamental type corresponding to C `unsigned long` + +The fundamental type corresponding to `i64` + +The fundamental type corresponding to `u64` + +The fundamental type corresponding to `f32` + +The fundamental type corresponding to `f64` + +The fundamental type corresponding to `String` + +The fundamental type corresponding to a pointer + +The fundamental type of GVariant + +The fundamental type from which all interfaces are derived + +The fundamental type from which all enumeration types are derived + +The fundamental type from which all flags types are derived + +The fundamental type from which all boxed types are derived + +The fundamental type from which all `GParamSpec` types are derived + +The fundamental type from which all objects are derived + +A non-fundamental type identified by value of type `usize` + +Types that are supported by GLib dynamic typing. + +Returns the type identifier of `Self`. + + +Same as [`get_prgname()`]. + +[`get_prgname()`]: fn.get_prgname.html + +Same as [`set_prgname()`]. + +[`set_prgname()`]: fn.set_prgname.html + + +`Value` binding and helper traits. + +The type of a [`Value`](struct.Value.html) is dynamic in that it generally +isn't known at compile time but once created a `Value` can't change its +type. + +[`TypedValue`](struct.TypedValue.html) has a statically known type and +dereferences to `Value` so it can be used everywhere `Value` references are +accepted. + +Supported types are `bool`, `i8`, `u8`, `i32`, `u32`, `i64`, `u64`, `f32`, +`f64`, `String` and objects (`T: IsA`). + +# Examples + +``` +use glib::prelude::*; // or `use gtk::prelude::*;` +use glib::{TypedValue, Value}; + +// Value and TypedValue implement From<&i32>, From<&str> +// and From>. Another option is the `ToValue` trait. +let mut num = 10.to_value(); +let mut hello = Value::from("Hello!"); +let none: Option<&str> = None; +let str_none = Value::from(none.clone()); +let typed_str_none = TypedValue::from(none); + +// `is` tests the type of the value. +assert!(num.is::()); +assert!(hello.is::()); + +// `get` tries to get a value of specific type and returns None +// if the type doesn't match or the value is None. +assert_eq!(num.get(), Some(10)); +assert_eq!(num.get::(), None); +assert_eq!(hello.get(), Some(String::from("Hello!"))); +assert_eq!(hello.get::(), Some(String::from("Hello!"))); +assert_eq!(str_none.get::(), None); + +// `typed` tries to convert a `Value` to `TypedValue`. +let mut typed_num = num.downcast::().unwrap(); +let mut typed_hello = hello.downcast::().unwrap(); + +// `str_none` is not an `i32` +assert!(str_none.downcast::().is_err()); + +// `get` +assert!(typed_hello.get().unwrap() == "Hello!"); +assert!(typed_str_none.get() == None); + +// Numeric types can't have value `None`, `get` always returns `Some`. +// Such types have `get_some`, which avoids unnecessary `unwrap`ping. +assert_eq!(typed_num.get().unwrap(), 10); +assert_eq!(typed_num.get_some(), 10); + +// `set_none` sets the value to `None` if the type supports it. +typed_hello.set_none(); +assert!(typed_hello.get().is_none()); + +// `set` takes an optional reference for types that support `None`. +typed_hello.set(Some("Hello again!")); +assert!(typed_hello.get().unwrap() == "Hello again!"); + +// `set_some` is the only setter for types that don't support `None`. +typed_num.set_some(&20); +assert_eq!(typed_num.get_some(), 20); +``` + +A generic value capable of carrying various types. + +Once created the type of the value can't be changed. + +Some types (e.g. `String` and objects) support `None` values while others +(e.g. numeric types) don't. + +See the [module documentation](index.html) for more details. + +Tries to downcast to a `TypedValue`. + +Returns `Ok(TypedValue)` if the value carries a type corresponding +to `T` and `Err(self)` otherwise. + +Tries to get a value of type `T`. + +Returns `Some` if the type is correct and the value is not `None`. + +This function doesn't distinguish between type mismatches and correctly +typed `None` values. Use `downcast` or `is` for that. + +Returns `true` if the type of the value corresponds to `T`. + +Returns the type of the value. + +Returns whether `Value`s of type `src` can be transformed to type `dst`. + +A statically typed [`Value`](struct.Value.html). + +It dereferences to `Value` and can be used everywhere `Value` references are +accepted. + +See the [module documentation](index.html) for more details. + +Returns the value. + +Types that don't support a `None` value always return `Some`. See +`get_some`. + +Returns the value. + +This method is only available for types that don't support a `None` +value. + +Sets the value. + +This method is only available for types that support a `None` value. + +Sets the value to `None`. + +This method is only available for types that support a `None` value. + +Sets the value. + +Converts to `Value`. + +Returns a `Value` clone of `self`. + +Returns the type identifer of `self`. + +This is the type of the value to be returned by `to_value`. + +Extracts a value. + +Types that don't support a `None` value always return `Some`. + +Extracts a value. + +Only implemented for types that don't support a `None` value. + +Sets a value. + +Only implemented for types that support a `None` value. + +Sets a value. + + +`Variant` binding and helper traits. + +[`Variant`](struct.Variant.html) is an immutable dynamically-typed generic +container. Its type and value are defined at construction and never change. + +`Variant` types are described by [`VariantType`](../struct.VariantType.html) +"type strings". + +Although `GVariant` supports arbitrarily complex types, this binding is +currently limited to the basic ones: `bool`, `u8`, `i16`, `u16`, `i32`, +`u32`, `i64`, `u64`, `f64` and `&str`/`String`. + +# Examples + +``` +use glib::prelude::*; // or `use gtk::prelude::*;` +use glib::Variant; + +// Using the `ToVariant` trait. +let num = 10.to_variant(); + +// `is` tests the type of the value. +assert!(num.is::()); + +// `get` tries to extract the value. +assert_eq!(num.get::(), Some(10)); +assert_eq!(num.get::(), None); + +// `Variant` implements `From` +let hello = Variant::from("Hello!"); + +// `get_str` tries to borrow a string slice. +assert_eq!(hello.get_str(), Some("Hello!")); +assert_eq!(num.get_str(), None); +``` + +A generic immutable value capable of carrying various types. + +See the [module documentation](index.html) for more details. + +Returns the type of the value. + +Returns `true` if the type of the value corresponds to `T`. + +Tries to extract a value of type `T`. + +Returns `Some` if `T` matches the variant's type. + +Tries to extract a `&str`. + +Returns `Some` if the variant has a string type (`s`, `o` or `g` type +strings). + +Converts to `Variant`. + +Returns a `Variant` clone of `self`. + +Extracts a value. + +Tries to extract a value. + +Returns `Some` if the variant's type matches `Self`. + +Returns `VariantType` of `Self`. + +Returns the `VariantType` corresponding to `Self`. + + +Describes `Variant` types. + +The `Variant` type system (based on the D-Bus one) describes types with +"type strings". `VariantType` is an owned immutable type string (you can +think of it as a `Box` statically guaranteed to be a valid type +string), `&VariantTy` is a borrowed one (like `&str`). + +Tries to create a `VariantType` from a string slice. + +Returns `Ok` if the string is a valid type string, `Err` otherwise. + +Describes `Variant` types. + +This is a borrowed counterpart of [`VariantType`](struct.VariantType.html). +Essentially it's a `str` statically guaranteed to be a valid type string. + +Tries to create a `&VariantTy` from a string slice. + +Returns `Ok` if the string is a valid type string, `Err` otherwise. + +Converts a type string into `&VariantTy` without any checks. + +Creates `&VariantTy` with a wildcard lifetime from a `GVariantType` +pointer. + +Returns a `GVariantType` pointer. + +Converts to a string slice. + + +`IMPL` The `glib_wrapper!` macro and miscellaneous wrapper traits. + +Defines a wrapper type and implements the appropriate traits. + +The basic syntax is + +```ignore +glib_wrapper! { + Documentation + pub struct $name($kind<$foreign>); + + match fn { + $fn_name => /* a closure-like expression , + ... + } +} +``` + +This creates a wrapper named `$name` around the foreign type `$foreign` +of `$kind` (one of `Boxed`, `Shared`, `Object`) using expressions from the `match fn` +block to implement type-specific low-level operations (the expression +will be evaluated in `unsafe` context). + +### Boxed + +Boxed records with single ownership. + +```ignore +glib_wrapper! { + Text buffer iterator + pub struct TextIter(Boxed); + + match fn { + copy => |ptr| ffi::gtk_text_iter_copy(ptr), + free => |ptr| ffi::gtk_text_iter_free(ptr), + } +} +``` + +`copy`: `|*const $foreign| -> *mut $foreign` creates a copy of the value. + +`free`: `|*mut $foreign|` frees the value. + +`get_type`: `||` (optional) returns the `Type`, if any + +### Shared + +Records with reference counted shared ownership. + +```ignore +glib_wrapper! { + Object holding timing information for a single frame. + pub struct FrameTimings(Shared); + + match fn { + ref => |ptr| ffi::gdk_frame_timings_ref(ptr), + unref => |ptr| ffi::gdk_frame_timings_unref(ptr), + } +} +``` + +`ref`: `|*mut $foreign|` increases the refcount. + +`unref`: `|*mut $foreign|` decreases the refcount. + +`get_type`: `||` (optional) returns the `Type`, if any + +### Object + +Objects -- classes and interfaces. + +```ignore +glib_wrapper! { + Object representing an input device. + pub struct Device(Object); + + match fn { + get_type => || ffi::gdk_device_get_type(), + } +} +``` + +```ignore +glib_wrapper! { + A container with just one child. + pub struct Bin(Object): Container, Widget, Buildable; + + match fn { + get_type => || ffi::gtk_bin_get_type(), + } +} +``` + +Implementing types from other crates requires specifying their FFI +counterparts as well: + +```ignore +glib_wrapper! { + pub struct Application(Object): [ + gio::Application => gio_ffi::GApplication, + gio::ActionGroup => gio_ffi::GActionGroup, + gio::ActionMap => gio_ffi::GActionMap, + ]; + + match fn { + get_type => || ffi::gtk_application_get_type(), + } +} +``` + +`get_type: || -> GType` returns the type identifier of the class or interface. + +A wrapper struct. + +Foreign type represented by the struct. diff --git a/glib/vendor.md b/glib/vendor.md new file mode 100644 index 00000000..9eade7a8 --- /dev/null +++ b/glib/vendor.md @@ -0,0 +1,5184 @@ + + +A simple refcounted data type representing an immutable sequence of zero or +more bytes from an unspecified origin. + +The purpose of a `Bytes` 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 `Bytes` without coordinating +their activities, resting assured that the byte data will not change or +move while they hold a reference. + +A `Bytes` 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 `MappedFile` or +memory from other allocators. + +`Bytes` work well as keys in `HashTable`. Use `Bytes::equal` and +`Bytes::hash` as parameters to `HashTable::new` or `HashTable::new_full`. +`Bytes` can also be used as keys in a `Tree` by passing the `Bytes::compare` +function to `Tree::new`. + +The data pointed to by this bytes must not be modified. For a mutable +array of bytes see `ByteArray`. Use `Bytes::unref_to_array` to create a +mutable array for a `Bytes` sequence. To create an immutable `Bytes` from +a mutable `ByteArray`, use the `ByteArray::free_to_bytes` function. + +Creates a new `Bytes` from `data`. + +`data` is copied. If `size` is 0, `data` may be `None`. +## `data` + + the data to be used for the bytes +## `size` +the size of `data` + +# Returns + +a new `Bytes` + +Creates a new `Bytes` from static data. + +`data` must be static (ie: never modified or freed). It may be `None` if `size` +is 0. +## `data` + + the data to be used for the bytes +## `size` +the size of `data` + +# Returns + +a new `Bytes` + +Creates a new `Bytes` 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 `Bytes` with memory from other allocators, see +`Bytes::new_with_free_func`. + +`data` may be `None` if `size` is 0. +## `data` + + the data to be used for the bytes +## `size` +the size of `data` + +# Returns + +a new `Bytes` + +Creates a `Bytes` from `data`. + +When the last reference is dropped, `free_func` will be called with the +`user_data` argument. + +`data` must not be modified after this call is made until `free_func` has +been called to indicate that the bytes is no longer in use. + +`data` may be `None` if `size` is 0. +## `data` + + the data to be used for the bytes +## `size` +the size of `data` +## `free_func` +the function to call to release the data +## `user_data` +data to pass to `free_func` + +# Returns + +a new `Bytes` + +Compares the two `Bytes` values. + +This function can be used to sort GBytes instances in lexographical order. +## `bytes2` +a pointer to a `Bytes` to compare with `self` + +# Returns + +a negative value if bytes2 is lesser, a positive value if bytes2 is + greater, and zero if bytes2 is equal to bytes1 + +Compares the two `Bytes` values being pointed to and returns +`true` if they are equal. + +This function can be passed to `HashTable::new` as the `key_equal_func` +parameter, when using non-`None` `Bytes` pointers as keys in a `HashTable`. +## `bytes2` +a pointer to a `Bytes` to compare with `self` + +# Returns + +`true` if the two keys match. + +Get the byte data in the `Bytes`. This data should not be modified. + +This function will always return the same pointer for a given `Bytes`. + +`None` may be returned if `size` is 0. This is not guaranteed, as the `Bytes` +may represent an empty string with `data` non-`None` and `size` as 0. `None` will +not be returned if `size` is non-zero. +## `size` +location to return size of byte data + +# Returns + + + a pointer to the byte data, or `None` + +Get the size of the byte data in the `Bytes`. + +This function will always return the same value for a given `Bytes`. + +# Returns + +the size + +Creates an integer hash code for the byte data in the `Bytes`. + +This function can be passed to `HashTable::new` as the `key_hash_func` +parameter, when using non-`None` `Bytes` pointers as keys in a `HashTable`. + +# Returns + +a hash value corresponding to the key. + +Creates a `Bytes` which is a subsection of another `Bytes`. The `offset` + +`length` may not be longer than the size of `self`. + +A reference to `self` will be held by the newly created `Bytes` until +the byte data is no longer needed. +## `offset` +offset which subsection starts at +## `length` +length of subsection + +# Returns + +a new `Bytes` + +Increase the reference count on `self`. + +# Returns + +the `Bytes` + +Releases a reference on `self`. This may result in the bytes being +freed. + +Unreferences the bytes, and returns a new mutable `ByteArray` containing +the same byte data. + +As an optimization, the byte data is transferred to the array without copying +if this was the last reference to bytes and bytes was created with +`Bytes::new`, `Bytes::new_take` or `ByteArray::free_to_bytes`. In all +other cases the data is copied. + +# Returns + +a new mutable `ByteArray` containing the same byte data + +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 `Bytes::new`, +`Bytes::new_take` or `ByteArray::free_to_bytes`. In all other cases the +data is copied. +## `size` +location to place the length of the returned data + +# Returns + +a pointer to the same byte data, which should be + freed with `g_free` + +An opaque structure representing a checksumming operation. +To create a new GChecksum, use `Checksum::new`. To free +a GChecksum, use `Checksum::free`. + +Creates a new `Checksum`, using the checksum algorithm `checksum_type`. +If the `checksum_type` is not known, `None` is returned. +A `Checksum` can be used to compute the checksum, or digest, of an +arbitrary binary blob, using different hashing algorithms. + +A `Checksum` works by feeding a binary blob through `Checksum::update` +until there is data to be checked; the digest can then be extracted +using `Checksum::get_string`, which will return the checksum as a +hexadecimal string; or `Checksum::get_digest`, which will return a +vector of raw bytes. Once either `Checksum::get_string` or +`Checksum::get_digest` have been called on a `Checksum`, the checksum +will be closed and it won't be possible to call `Checksum::update` +on it anymore. +## `checksum_type` +the desired type of checksum + +# Returns + +the newly created `Checksum`, or `None`. + Use `Checksum::free` to free the memory allocated by it. + +Copies a `Checksum`. If `self` has been closed, by calling +`Checksum::get_string` or `Checksum::get_digest`, the copied +checksum will be closed as well. + +# Returns + +the copy of the passed `Checksum`. Use `Checksum::free` + when finished using it. + +Frees the memory allocated for `self`. + +Gets the digest from `self` 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 `Checksum` is closed and can +no longer be updated with `Checksum::update`. +## `buffer` +output buffer +## `digest_len` +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 `Checksum` can no longer be +updated with `Checksum::update`. + +The hexadecimal characters will be lower case. + +# Returns + +the hexadecimal representation of the checksum. The + returned string is owned by the checksum and should not be modified + or freed. + +Resets the state of the `self` back to its initial state. + +Feeds `data` into an existing `Checksum`. The checksum must still be +open, that is `Checksum::get_string` or `Checksum::get_digest` must +not have been called on `self`. +## `data` +buffer used to compute the checksum +## `length` +size of the buffer, or -1 if it is a null-terminated string. + +Gets the length in bytes of digests of type `checksum_type` +## `checksum_type` +a `ChecksumType` + +# Returns + +the checksum length, or -1 if `checksum_type` is +not supported. + +The hashing algorithm to be used by `Checksum` when performing the +digest of some data. + +Note that the `ChecksumType` 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) + +Enumeration representing a month; values are `DateMonth::January`, +`DateMonth::February`, etc. `DateMonth::BadMonth` 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 `DateTime` 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 `None`. + +You should release the return value by calling `DateTime::unref` +when you are done with it. +## `tz` +a `TimeZone` +## `year` +the year component of the date +## `month` +the month component of the date +## `day` +the day component of the date +## `hour` +the hour component of the date +## `minute` +the minute component of the date +## `seconds` +the number of seconds past the minute + +# Returns + +a new `DateTime`, or `None` + +Creates a `DateTime` corresponding to the given `TimeVal` `tv` in the +local time zone. + +The time contained in a `TimeVal` 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 `None`) if `tv` represents a time outside +of the supported range of `DateTime`. + +You should release the return value by calling `DateTime::unref` +when you are done with it. +## `tv` +a `TimeVal` + +# Returns + +a new `DateTime`, or `None` + +Creates a `DateTime` corresponding to the given `TimeVal` `tv` in UTC. + +The time contained in a `TimeVal` is always stored in the form of +seconds elapsed since 1970-01-01 00:00:00 UTC. + +This call can fail (returning `None`) if `tv` represents a time outside +of the supported range of `DateTime`. + +You should release the return value by calling `DateTime::unref` +when you are done with it. +## `tv` +a `TimeVal` + +# Returns + +a new `DateTime`, or `None` + +Creates a `DateTime` 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 `None`) if `t` represents a time outside +of the supported range of `DateTime`. + +You should release the return value by calling `DateTime::unref` +when you are done with it. +## `t` +the Unix time + +# Returns + +a new `DateTime`, or `None` + +Creates a `DateTime` 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 `None`) if `t` represents a time outside +of the supported range of `DateTime`. + +You should release the return value by calling `DateTime::unref` +when you are done with it. +## `t` +the Unix time + +# Returns + +a new `DateTime`, or `None` + +Creates a new `DateTime` corresponding to the given date and time in +the local time zone. + +This call is equivalent to calling `DateTime::new` with the time +zone returned by `TimeZone::new_local`. +## `year` +the year component of the date +## `month` +the month component of the date +## `day` +the day component of the date +## `hour` +the hour component of the date +## `minute` +the minute component of the date +## `seconds` +the number of seconds past the minute + +# Returns + +a `DateTime`, or `None` + +Creates a `DateTime` 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 `DateTime::unref` +when you are done with it. +## `tz` +a `TimeZone` + +# Returns + +a new `DateTime`, or `None` + +Creates a `DateTime` corresponding to this exact instant in the local +time zone. + +This is equivalent to calling `DateTime::new_now` with the time +zone returned by `TimeZone::new_local`. + +# Returns + +a new `DateTime`, or `None` + +Creates a `DateTime` corresponding to this exact instant in UTC. + +This is equivalent to calling `DateTime::new_now` with the time +zone returned by `TimeZone::new_utc`. + +# Returns + +a new `DateTime`, or `None` + +Creates a new `DateTime` corresponding to the given date and time in +UTC. + +This call is equivalent to calling `DateTime::new` with the time +zone returned by `TimeZone::new_utc`. +## `year` +the year component of the date +## `month` +the month component of the date +## `day` +the day component of the date +## `hour` +the hour component of the date +## `minute` +the minute component of the date +## `seconds` +the number of seconds past the minute + +# Returns + +a `DateTime`, or `None` + +Creates a copy of `self` and adds the specified timespan to the copy. +## `timespan` +a `TimeSpan` + +# Returns + +the newly created `DateTime` which should be freed with + `DateTime::unref`. + +Creates a copy of `self` and adds the specified number of days to the +copy. Add negative values to subtract days. +## `days` +the number of days + +# Returns + +the newly created `DateTime` which should be freed with + `DateTime::unref`. + +Creates a new `DateTime` adding the specified values to the current date and +time in `self`. Add negative values to subtract. +## `years` +the number of years to add +## `months` +the number of months to add +## `days` +the number of days to add +## `hours` +the number of hours to add +## `minutes` +the number of minutes to add +## `seconds` +the number of seconds to add + +# Returns + +the newly created `DateTime` that should be freed with + `DateTime::unref`. + +Creates a copy of `self` and adds the specified number of hours. +Add negative values to subtract hours. +## `hours` +the number of hours to add + +# Returns + +the newly created `DateTime` which should be freed with + `DateTime::unref`. + +Creates a copy of `self` adding the specified number of minutes. +Add negative values to subtract minutes. +## `minutes` +the number of minutes to add + +# Returns + +the newly created `DateTime` which should be freed with + `DateTime::unref`. + +Creates a copy of `self` and adds the specified number of months to the +copy. Add negative values to subtract months. +## `months` +the number of months + +# Returns + +the newly created `DateTime` which should be freed with + `DateTime::unref`. + +Creates a copy of `self` and adds the specified number of seconds. +Add negative values to subtract seconds. +## `seconds` +the number of seconds to add + +# Returns + +the newly created `DateTime` which should be freed with + `DateTime::unref`. + +Creates a copy of `self` and adds the specified number of weeks to the +copy. Add negative values to subtract weeks. +## `weeks` +the number of weeks + +# Returns + +the newly created `DateTime` which should be freed with + `DateTime::unref`. + +Creates a copy of `self` and adds the specified number of years to the +copy. Add negative values to subtract years. +## `years` +the number of years + +# Returns + +the newly created `DateTime` which should be freed with + `DateTime::unref`. + +Calculates the difference in time between `self` and `begin`. The +`TimeSpan` that is returned is effectively `self` - `begin` (ie: +positive if the first parameter is larger). +## `begin` +a `DateTime` + +# Returns + +the difference between the two `DateTime`, as a time + span expressed in microseconds. + +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 `DateTime::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. +## `format` +a valid UTF-8 string, containing the format for the + `DateTime` + +# Returns + +a newly allocated string formatted to the requested format + or `None` in the case that there was an error. The string + should be freed with `g_free`. + +Retrieves the day of the month represented by `self` in the gregorian +calendar. + +# Returns + +the day of the month + +Retrieves the ISO 8601 day of the week on which `self` falls (1 is +Monday, 2 is Tuesday... 7 is Sunday). + +# Returns + +the day of the week + +Retrieves the day of the year represented by `self` in the Gregorian +calendar. + +# Returns + +the day of the year + +Retrieves the hour of the day represented by `self` + +# Returns + +the hour of the day + +Retrieves the microsecond of the date represented by `self` + +# Returns + +the microsecond of the second + +Retrieves the minute of the hour represented by `self` + +# Returns + +the minute of the hour + +Retrieves the month of the year represented by `self` in the Gregorian +calendar. + +# Returns + +the month represented by `self` + +Retrieves the second of the minute represented by `self` + +# Returns + +the second represented by `self` + +Retrieves the number of seconds since the start of the last minute, +including the fractional part. + +# Returns + +the number of seconds + +Determines the time zone abbreviation to be used at the time and in +the time zone of `self`. + +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. + +# Returns + +the time zone abbreviation. The returned + string is owned by the `DateTime` and it should not be + modified or freed + +Determines the offset to UTC in effect at the time and in the time +zone of `self`. + +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 `self` represents UTC time, then the offset is always zero. + +# Returns + +the number of microseconds that should be added to UTC to + get the local time + +Returns the ISO 8601 week-numbering year in which the week containing +`self` falls. + +This function, taken together with `DateTime::get_week_of_year` and +`DateTime::get_day_of_week` can be used to determine the full ISO +week date on which `self` falls. + +This is usually equal to the normal Gregorian year (as returned by +`DateTime::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. + +# Returns + +the ISO 8601 week-numbering year for `self` + +Returns the ISO 8601 week number for the week containing `self`. +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. + +# Returns + +the ISO 8601 week number for `self`. + +Retrieves the year represented by `self` in the Gregorian calendar. + +# Returns + +the year represented by `self` + +Retrieves the Gregorian day, month, and year of a given `DateTime`. +## `year` +the return location for the gregorian year, or `None`. +## `month` +the return location for the month of the year, or `None`. +## `day` +the return location for the day of the month, or `None`. + +Determines if daylight savings time is in effect at the time and in +the time zone of `self`. + +# Returns + +`true` if daylight savings time is in effect + +Atomically increments the reference count of `self` by one. + +# Returns + +the `DateTime` with the reference count increased + +Creates a new `DateTime` corresponding to the same instant in time as +`self`, but in the local time zone. + +This call is equivalent to calling `DateTime::to_timezone` with the +time zone returned by `TimeZone::new_local`. + +# Returns + +the newly created `DateTime` + +Stores the instant in time that `self` represents into `tv`. + +The time contained in a `TimeVal` is always stored in the form of +seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time +zone associated with `self`. + +On systems where 'long' is 32bit (ie: all 32bit systems and all +Windows systems), a `TimeVal` is incapable of storing the entire +range of values that `DateTime` 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. +## `tv` +a `TimeVal` to modify + +# Returns + +`true` if successful, else `false` + +Create a new `DateTime` corresponding to the same instant in time as +`self`, 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 `DateTime::unref` +when you are done with it. +## `tz` +the new `TimeZone` + +# Returns + +a new `DateTime`, or `None` + +Gives the Unix time corresponding to `self`, 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 `self`. + +# Returns + +the Unix time corresponding to `self` + +Creates a new `DateTime` corresponding to the same instant in time as +`self`, but in UTC. + +This call is equivalent to calling `DateTime::to_timezone` with the +time zone returned by `TimeZone::new_utc`. + +# Returns + +the newly created `DateTime` + +Atomically decrements the reference count of `self` by one. + +When the reference count reaches zero, the resources allocated by +`self` are freed + +A comparison function for `GDateTimes` that is suitable +as a `GCompareFunc`. Both `GDateTimes` must be non-`None`. +## `dt1` +first `DateTime` to compare +## `dt2` +second `DateTime` to compare + +# Returns + +-1, 0 or 1 if `dt1` is less than, equal to or greater + than `dt2`. + +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. +## `dt1` +a `DateTime` +## `dt2` +a `DateTime` + +# Returns + +`true` if `dt1` and `dt2` are equal + +Hashes `datetime` into a `guint`, suitable for use within `HashTable`. +## `datetime` +a `DateTime` + +# Returns + +a `guint` containing the hash + +Enumeration representing a day of the week; `DateWeekday::Monday`, +`DateWeekday::Tuesday`, etc. `DateWeekday::BadWeekday` is an invalid weekday. + +invalid value + +Monday + +Tuesday + +Wednesday + +Thursday + +Friday + +Saturday + +Sunday + +The `GError` structure contains information about +an error that has occurred. + +Creates a new `Error` with the given `domain` and `code`, +and a message formatted with `format`. +## `domain` +error domain +## `code` +error code +## `format` +`printf`-style format for error message + +# Returns + +a new `Error` + +Creates a new `Error`; unlike `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. +## `domain` +error domain +## `code` +error code +## `message` +error message + +# Returns + +a new `Error` + +Creates a new `Error` with the given `domain` and `code`, +and a message formatted with `format`. +## `domain` +error domain +## `code` +error code +## `format` +`printf`-style format for error message +## `args` +`va_list` of parameters for the message format + +# Returns + +a new `Error` + +Makes a copy of `self`. + +# Returns + +a new `Error` + +Frees a `Error` and associated resources. + +Returns `true` if `self` matches `domain` and `code`, `false` +otherwise. In particular, when `self` is `None`, `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. +## `domain` +an error domain +## `code` +an error code + +# Returns + +whether `self` has `domain` and `code` + +The GKeyFile struct contains only private data +and should not be accessed directly. + +Creates a new empty `KeyFile` object. Use +`KeyFile::load_from_file`, `KeyFile::load_from_data`, +`KeyFile::load_from_dirs` or `KeyFile::load_from_data_dirs` to +read an existing key file. + +# Returns + +an empty `KeyFile`. + +Clears all keys and groups from `self`, and decreases the +reference count by 1. If the reference count reaches zero, +frees the key file and all its allocated memory. + +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 `KeyFileError::KeyNotFound`. Likewise, if the value +associated with `key` cannot be interpreted as a boolean then `false` +is returned and `error` is set to `KeyFileError::InvalidValue`. +## `group_name` +a group name +## `key` +a key + +# Returns + +the value associated with the key as a boolean, + or `false` if the key was not found or could not be parsed. + +Returns the values associated with `key` under `group_name` as +booleans. + +If `key` cannot be found then `None` is returned and `error` is set to +`KeyFileError::KeyNotFound`. Likewise, if the values associated +with `key` cannot be interpreted as booleans then `None` is returned +and `error` is set to `KeyFileError::InvalidValue`. +## `group_name` +a group name +## `key` +a key +## `length` +the number of booleans returned + +# Returns + + + the values associated with the key as a list of booleans, or `None` 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. + +Retrieves a comment above `key` from `group_name`. +If `key` is `None` then `comment` will be read from above +`group_name`. If both `key` and `group_name` are `None`, then +`comment` will be read from above the first group in the file. + +Note that the returned string includes the '#' comment markers. +## `group_name` +a group name, or `None` +## `key` +a key + +# Returns + +a comment that should be freed with `g_free` + +Returns the value associated with `key` under `group_name` as a +double. If `group_name` is `None`, the start_group is used. + +If `key` cannot be found then 0.0 is returned and `error` is set to +`KeyFileError::KeyNotFound`. Likewise, if the value associated +with `key` cannot be interpreted as a double then 0.0 is returned +and `error` is set to `KeyFileError::InvalidValue`. +## `group_name` +a group name +## `key` +a key + +# Returns + +the value associated with the key as a double, or + 0.0 if the key was not found or could not be parsed. + +Returns the values associated with `key` under `group_name` as +doubles. + +If `key` cannot be found then `None` is returned and `error` is set to +`KeyFileError::KeyNotFound`. Likewise, if the values associated +with `key` cannot be interpreted as doubles then `None` is returned +and `error` is set to `KeyFileError::InvalidValue`. +## `group_name` +a group name +## `key` +a key +## `length` +the number of doubles returned + +# Returns + + + the values associated with the key as a list of doubles, or `None` 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. + +Returns all groups in the key file loaded with `self`. +The array of returned groups will be `None`-terminated, so +`length` may optionally be `None`. +## `length` +return location for the number of returned groups, or `None` + +# Returns + +a newly-allocated `None`-terminated array of strings. + Use `g_strfreev` to free it. + +Returns the value associated with `key` under `group_name` as a signed +64-bit integer. This is similar to `KeyFile::get_integer` but can return +64-bit results without truncation. +## `group_name` +a non-`None` group name +## `key` +a non-`None` key + +# Returns + +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. + +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 +`KeyFileError::KeyNotFound`. Likewise, if the value associated +with `key` cannot be interpreted as an integer then 0 is returned +and `error` is set to `KeyFileError::InvalidValue`. +## `group_name` +a group name +## `key` +a key + +# Returns + +the value associated with the key as an integer, or + 0 if the key was not found or could not be parsed. + +Returns the values associated with `key` under `group_name` as +integers. + +If `key` cannot be found then `None` is returned and `error` is set to +`KeyFileError::KeyNotFound`. Likewise, if the values associated +with `key` cannot be interpreted as integers then `None` is returned +and `error` is set to `KeyFileError::InvalidValue`. +## `group_name` +a group name +## `key` +a key +## `length` +the number of integers returned + +# Returns + + + the values associated with the key as a list of integers, or `None` 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. + +Returns all keys for the group name `group_name`. The array of +returned keys will be `None`-terminated, so `length` may +optionally be `None`. In the event that the `group_name` cannot +be found, `None` is returned and `error` is set to +`KeyFileError::GroupNotFound`. +## `group_name` +a group name +## `length` +return location for the number of keys returned, or `None` + +# Returns + +a newly-allocated `None`-terminated array of strings. + Use `g_strfreev` to free it. + +Returns the value associated with `key` under `group_name` +translated in the given `locale` if available. If `locale` is +`None` then the current locale is assumed. + +If `key` cannot be found then `None` is returned and `error` is set +to `KeyFileError::KeyNotFound`. If the value associated +with `key` cannot be interpreted or no suitable translation can +be found then the untranslated value is returned. +## `group_name` +a group name +## `key` +a key +## `locale` +a locale identifier or `None` + +# Returns + +a newly allocated string or `None` if the specified + key cannot be found. + +Returns the values associated with `key` under `group_name` +translated in the given `locale` if available. If `locale` is +`None` then the current locale is assumed. + +If `key` cannot be found then `None` is returned and `error` is set +to `KeyFileError::KeyNotFound`. 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 `None`-terminated, so `length` may optionally +be `None`. +## `group_name` +a group name +## `key` +a key +## `locale` +a locale identifier or `None` +## `length` +return location for the number of returned strings or `None` + +# Returns + +a newly allocated `None`-terminated string array + or `None` if the key isn't found. The string array should be freed + with `g_strfreev`. + +Returns the name of the start group of the file. + +# Returns + +The start group of the key file. + +Returns the string value associated with `key` under `group_name`. +Unlike `KeyFile::get_value`, this function handles escape sequences +like \s. + +In the event the key cannot be found, `None` is returned and +`error` is set to `KeyFileError::KeyNotFound`. In the +event that the `group_name` cannot be found, `None` is returned +and `error` is set to `KeyFileError::GroupNotFound`. +## `group_name` +a group name +## `key` +a key + +# Returns + +a newly allocated string or `None` if the specified + key cannot be found. + +Returns the values associated with `key` under `group_name`. + +In the event the key cannot be found, `None` is returned and +`error` is set to `KeyFileError::KeyNotFound`. In the +event that the `group_name` cannot be found, `None` is returned +and `error` is set to `KeyFileError::GroupNotFound`. +## `group_name` +a group name +## `key` +a key +## `length` +return location for the number of returned strings, or `None` + +# Returns + + + a `None`-terminated string array or `None` if the specified + key cannot be found. The array should be freed with `g_strfreev`. + +Returns the value associated with `key` under `group_name` as an unsigned +64-bit integer. This is similar to `KeyFile::get_integer` but can return +large positive results without truncation. +## `group_name` +a non-`None` group name +## `key` +a non-`None` key + +# Returns + +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. + +Returns the raw value associated with `key` under `group_name`. +Use `KeyFile::get_string` to retrieve an unescaped UTF-8 string. + +In the event the key cannot be found, `None` is returned and +`error` is set to `KeyFileError::KeyNotFound`. In the +event that the `group_name` cannot be found, `None` is returned +and `error` is set to `KeyFileError::GroupNotFound`. +## `group_name` +a group name +## `key` +a key + +# Returns + +a newly allocated string or `None` if the specified + key cannot be found. + +Looks whether the key file has the group `group_name`. +## `group_name` +a group name + +# Returns + +`true` if `group_name` is a part of `self`, `false` +otherwise. + +Looks whether the key file has the key `key` in the group +`group_name`. + +Note that this function does not follow the rules for `Error` strictly; +the return value both carries meaning and signals an error. To use +this function, you must pass a `Error` pointer in `error`, and check +whether it is not `None` to see if an error occurred. + +Language bindings should use `KeyFile::get_value` to test whether +or not a key exists. +## `group_name` +a group name +## `key` +a key name + +# Returns + +`true` if `key` is a part of `group_name`, `false` otherwise + +Loads a key file from the data in `bytes` into an empty `KeyFile` structure. +If the object cannot be created then `error` is set to a `KeyFileError`. + +Feature: `v2_50` + +## `bytes` +a `Bytes` +## `flags` +flags from `KeyFileFlags` + +# Returns + +`true` if a key file could be loaded, `false` otherwise + +Loads a key file from memory into an empty `KeyFile` structure. +If the object cannot be created then `error` is set to a `KeyFileError`. +## `data` +key file loaded in memory +## `length` +the length of `data` in bytes (or (gsize)-1 if data is nul-terminated) +## `flags` +flags from `KeyFileFlags` + +# Returns + +`true` if a key file could be loaded, `false` otherwise + +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 `self` 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 `FileError` or `KeyFileError`. +## `file` +a relative path to a filename to open and parse +## `full_path` +return location for a string containing the full path + of the file, or `None` +## `flags` +flags from `KeyFileFlags` + +# Returns + +`true` if a key file could be loaded, `false` othewise + +This function looks for a key file named `file` in the paths +specified in `search_dirs`, loads the file into `self` 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 `FileError` or +`KeyFileError`. +## `file` +a relative path to a filename to open and parse +## `search_dirs` +`None`-terminated array of directories to search +## `full_path` +return location for a string containing the full path + of the file, or `None` +## `flags` +flags from `KeyFileFlags` + +# Returns + +`true` if a key file could be loaded, `false` otherwise + +Loads a key file into an empty `KeyFile` structure. +If the file could not be loaded then `error` is set to +either a `FileError` or `KeyFileError`. +## `file` +the path of a filename to load, in the GLib filename encoding +## `flags` +flags from `KeyFileFlags` + +# Returns + +`true` if a key file could be loaded, `false` otherwise + +Increases the reference count of `self`. + +# Returns + +the same `self`. + +Removes a comment above `key` from `group_name`. +If `key` is `None` then `comment` will be removed above `group_name`. +If both `key` and `group_name` are `None`, then `comment` will +be removed above the first group in the file. +## `group_name` +a group name, or `None` +## `key` +a key + +# Returns + +`true` if the comment was removed, `false` otherwise + +Removes the specified group, `group_name`, +from the key file. +## `group_name` +a group name + +# Returns + +`true` if the group was removed, `false` otherwise + +Removes `key` in `group_name` from the key file. +## `group_name` +a group name +## `key` +a key name to remove + +# Returns + +`true` if the key was removed, `false` otherwise + +Writes the contents of `self` to `filename` using +`g_file_set_contents`. + +This function can fail for any of the reasons that +`g_file_set_contents` may fail. + +Feature: `v2_40` + +## `filename` +the name of the file to write to + +# Returns + +`true` if successful, else `false` with `error` set + +Associates a new boolean value with `key` under `group_name`. +If `key` cannot be found then it is created. +## `group_name` +a group name +## `key` +a key +## `value` +`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 `None`, the start_group is used. +## `group_name` +a group name +## `key` +a key +## `list` +an array of boolean values +## `length` +length of `list` + +Places a comment above `key` from `group_name`. + +If `key` is `None` then `comment` will be written above `group_name`. +If both `key` and `group_name` are `None`, 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`. +## `group_name` +a group name, or `None` +## `key` +a key +## `comment` +a comment + +# Returns + +`true` if the comment was written, `false` otherwise + +Associates a new double value with `key` under `group_name`. +If `key` cannot be found then it is created. +## `group_name` +a group name +## `key` +a key +## `value` +an double value + +Associates a list of double values with `key` under +`group_name`. If `key` cannot be found then it is created. +## `group_name` +a group name +## `key` +a key +## `list` +an array of double values +## `length` +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. +## `group_name` +a group name +## `key` +a key +## `value` +an integer value + +Associates a new integer value with `key` under `group_name`. +If `key` cannot be found then it is created. +## `group_name` +a group name +## `key` +a key +## `value` +an integer value + +Associates a list of integer values with `key` under `group_name`. +If `key` cannot be found then it is created. +## `group_name` +a group name +## `key` +a key +## `list` +an array of integer values +## `length` +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 ';'. +## `separator` +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. +## `group_name` +a group name +## `key` +a key +## `locale` +a locale identifier +## `string` +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. +## `group_name` +a group name +## `key` +a key +## `locale` +a locale identifier +## `list` +a `None`-terminated array of locale string values +## `length` +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 `KeyFile::set_value`, this function handles characters +that need escaping, such as newlines. +## `group_name` +a group name +## `key` +a key +## `string` +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. +## `group_name` +a group name +## `key` +a key +## `list` +an array of string values +## `length` +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. +## `group_name` +a group name +## `key` +a key +## `value` +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 +`KeyFile::set_string`. +## `group_name` +a group name +## `key` +a key +## `value` +a string + +This function outputs `self` as a string. + +Note that this function never reports an error, +so it is safe to pass `None` as `error`. +## `length` +return location for the length of the + returned string, or `None` + +# Returns + +a newly allocated string holding + the contents of the `KeyFile` + +Decreases the reference count of `self` by 1. If the reference count +reaches zero, frees the key file and all its allocated memory. + +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 + +The `GMainContext` struct is an opaque data +type representing a set of sources to be handled in a main loop. + +Creates a new `MainContext` structure. + +# Returns + +the new `MainContext` + +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 `MainContext::release` +is called as many times as `MainContext::acquire`. + +You must be the owner of a context before you +can call `MainContext::prepare`, `MainContext::query`, +`MainContext::check`, `MainContext::dispatch`. + +# Returns + +`true` if the operation succeeded, and + this thread is now the owner of `self`. + +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 `Source::add_unix_fd` instead. +## `fd` +a `PollFD` structure holding information about a file + descriptor to watch. +## `priority` +the priority for this file descriptor which should be + the same as the priority used for `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 +`MainContext::acquire` before you may call this function. +## `max_priority` +the maximum numerical priority of sources to check +## `fds` +array of `PollFD`'s that was passed to + the last call to `MainContext::query` +## `n_fds` +return value of `MainContext::query` + +# Returns + +`true` if some sources are ready to be dispatched. + +Dispatches all pending sources. + +You must have successfully acquired the context with +`MainContext::acquire` before you may call this function. + +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. +## `funcs` +the `source_funcs` passed to `Source::new`. +## `user_data` +the user data from the callback. + +# Returns + +the source, if one was found, otherwise `None` + +Finds a `Source` given a pair of context and ID. + +It is a programmer error to attempt to lookup 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. +## `source_id` +the source ID, as returned by `Source::get_id`. + +# Returns + +the `Source` + +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. +## `user_data` +the user_data for the callback. + +# Returns + +the source, if one was found, otherwise `None` + +Gets the poll function set by `MainContext::set_poll_func`. + +# Returns + +the poll function + +Invokes a function in such a way that `self` is owned during the +invocation of `function`. + +If `self` is `None` then the global default main context — as +returned by `MainContext::default` — is used. + +If `self` is owned by the current thread, `function` is called +directly. Otherwise, if `self` is the thread-default main context +of the current thread and `MainContext::acquire` succeeds, then +`function` is called and `MainContext::release` is called +afterwards. + +In any other case, an idle source is created to call `function` and +that source is attached to `self` (presumably to be run in another +thread). The idle source is attached with `G_PRIORITY_DEFAULT` +priority. If you want a different priority, use +`MainContext::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). +## `function` +function to call +## `data` +data to pass to `function` + +Invokes a function in such a way that `self` is owned during the +invocation of `function`. + +This function is the same as `MainContext::invoke` except that it +lets you specify the priority incase `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. +## `priority` +the priority at which to run `function` +## `function` +function to call +## `data` +data to pass to `function` +## `notify` +a function to call when `data` is no longer in use, or `None`. + +Determines whether this thread holds the (recursive) +ownership of this `MainContext`. This is useful to +know before waiting on another thread that may be +blocking to get ownership of `self`. + +# Returns + +`true` if current thread is owner of `self`. + +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 +`MainContext::iteration` to return `false`, since the wait may +be interrupted for other reasons than an event source becoming ready. +## `may_block` +whether the call may block. + +# Returns + +`true` if events were dispatched. + +Checks if any sources have pending events for the given context. + +# Returns + +`true` if events are pending. + +Pops `self` off the thread-default context stack (verifying that +it was on the top of the stack). + +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 +`MainContext::acquire` before you may call this function. +## `priority` +location to store priority of highest priority + source already ready. + +# Returns + +`true` if some source is ready to be dispatched + prior to polling. + +Acquires `self` 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 `self` 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 `MainContext::get_thread_default`, +not the one returned by `MainContext::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 `MainContext` which will be run by a +`MainLoop` in that thread, to set a new default context for all +async operations in that thread. In this case you may not need to +ever call `MainContext::pop_thread_default`, assuming you want the +new `MainContext` to be the default for the whole lifecycle of the +thread. + +If you don't have control over how the new thread was created (e.g. +in the new thread isn't newly created, or if the thread life +cycle is managed by a `ThreadPool`), it is always suggested to wrap +the logic that needs to use the new `MainContext` inside a +`MainContext::push_thread_default` / `MainContext::pop_thread_default` +pair, otherwise threads that are re-used will end up never explicitly +releasing the `MainContext` reference they hold. + +In some cases you may want to schedule a single operation in a +non-default context, or temporarily use a non-default context in +the main thread. In that case, you can wrap the call to the +asynchronous operation inside a +`MainContext::push_thread_default` / +`MainContext::pop_thread_default` pair, but it is up to you to +ensure that no other asynchronous operations accidentally get +started while the non-default context is active. + +Beware that libraries that predate this function may not correctly +handle being used from a thread with a thread-default context. Eg, +see `g_file_supports_thread_contexts`. + +Determines information necessary to poll this main loop. + +You must have successfully acquired the context with +`MainContext::acquire` before you may call this function. +## `max_priority` +maximum priority source to check +## `timeout_` +location to store timeout to be used in polling +## `fds` +location to + store `PollFD` records that need to be polled. +## `n_fds` +length of `fds`. + +# Returns + +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. + +Increases the reference count on a `MainContext` object by one. + +# Returns + +the `self` that was passed in (since 2.6) + +Releases ownership of a context previously acquired by this thread +with `MainContext::acquire`. If the context was acquired multiple +times, the ownership will be released only when `MainContext::release` +is called as many times as it was acquired. + +Removes file descriptor from the set of file descriptors to be +polled for a particular context. +## `fd` +a `PollFD` descriptor previously added with `MainContext::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. +## `func` +the function to call to poll all file descriptors + +Decreases the reference count on a `MainContext` object by one. If +the result is zero, free the context and free all associated memory. + +Tries to become the owner of the specified context, +as with `MainContext::acquire`. But if another thread +is the owner, atomically drop `mutex` and wait on `cond` until +that owner releases ownership or until `cond` is signaled, then +try again (once) to become the owner. +## `cond` +a condition variable +## `mutex` +a mutex, currently held + +# Returns + +`true` if the operation succeeded, and + this thread is now the owner of `self`. + +If `self` is currently blocking in `MainContext::iteration` +waiting for a source to become ready, cause it to stop blocking +and return. Otherwise, cause the next invocation of +`MainContext::iteration` to return without blocking. + +This API is useful for low-level control over `MainContext`; for +example, integrating it with main loop implementations such as +`MainLoop`. + +Another related use for this function is when implementing a main +loop with a termination condition, computed from multiple threads: + + +```C + #define NUM_TASKS 10 + static volatile gint tasks_remaining = NUM_TASKS; + ... + + while (g_atomic_int_get (&tasks_remaining) != 0) + g_main_context_iteration (NULL, TRUE); +``` + +Then in a thread: + +```C + perform_work(); + + if (g_atomic_int_dec_and_test (&tasks_remaining)) + g_main_context_wakeup (NULL); +``` + +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 +`MainContext::get_thread_default`. + +# Returns + +the global default main context. + +Gets the thread-default `MainContext` 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 +`MainContext::ref_thread_default` to get a `MainContext` 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 `None` if you are running in the default thread.) + +If you need to hold a reference on the context, use +`MainContext::ref_thread_default` instead. + +# Returns + +the thread-default `MainContext`, or +`None` if the thread-default context is the global default context. + +Gets the thread-default `MainContext` for this thread, as with +`MainContext::get_thread_default`, but also adds a reference to +it with `MainContext::ref`. In addition, unlike +`MainContext::get_thread_default`, if the thread-default context +is the global default context, this will return that `MainContext` +(with a ref added to it) rather than returning `None`. + +# Returns + +the thread-default `MainContext`. Unref + with `MainContext::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 `MainLoop` structure. +## `context` +a `MainContext` (if `None`, the default context will be used). +## `is_running` +set to `true` to indicate that the loop is running. This +is not very important since calling `MainLoop::run` will set this to +`true` anyway. + +# Returns + +a new `MainLoop`. + +Returns the `MainContext` of `self`. + +# Returns + +the `MainContext` of `self` + +Checks to see if the main loop is currently being run via `MainLoop::run`. + +# Returns + +`true` if the mainloop is currently being run. + +Stops a `MainLoop` from running. Any calls to `MainLoop::run` +for the loop will return. + +Note that sources that have already been dispatched when +`MainLoop::quit` is called will still be executed. + +Increases the reference count on a `MainLoop` object by one. + +# Returns + +`self` + +Runs a main loop until `MainLoop::quit` is called on the loop. +If this is called for the thread of the loop's `MainContext`, +it will process events from the loop, otherwise it will +simply wait. + +Decreases the reference count on a `MainLoop` object by one. If +the result is zero, free the loop and free all associated memory. + +The `GSource` struct is an opaque data type +representing an event source. + +Creates a new `Source` structure. The size is specified to +allow creating structures derived from `Source` that contain +additional data. The size passed in must be at least +`sizeof (GSource)`. + +The source will not initially be associated with any `MainContext` +and must be added to one with `Source::attach` before it will be +executed. +## `source_funcs` +structure containing functions that implement + the sources behavior. +## `struct_size` +size of the `Source` structure to create. + +# Returns + +the newly-created `Source`. + +Adds `child_source` to `self` as a "polled" source; when `self` is +added to a `MainContext`, `child_source` will be automatically added +with the same priority, when `child_source` is triggered, it will +cause `self` to dispatch (in addition to calling its own +callback), and when `self` is destroyed, it will destroy +`child_source` as well. (`self` 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). + +`self` 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 `Source`. +Do not call this API on a `Source` that you did not create. +## `child_source` +a second `Source` that `self` should "poll" + +Adds a file descriptor to the set of file descriptors polled for +this source. This is usually combined with `Source::new` to add an +event source. The event source's check function will typically test +the `revents` field in the `PollFD` struct and return `true` if events need +to be processed. + +This API is only intended to be used by implementations of `Source`. +Do not call this API on a `Source` that you did not create. + +Using this API forces the linear scanning of event sources on each +main loop iteration. Newly-written event sources should try to use +`Source::add_unix_fd` instead of this API. +## `fd` +a `PollFD` structure holding information about a file + descriptor to watch. + +Monitors `fd` for the IO events in `events`. + +The tag returned by this function can be used to remove or modify the +monitoring of the fd using `Source::remove_unix_fd` or +`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 `Source`. +Do not call this API on a `Source` that you did not create. + +As the name suggests, this function is not available on Windows. + +Feature: `v2_36` + +## `fd` +the fd to monitor +## `events` +an event mask + +# Returns + +an opaque tag + +Adds a `Source` to a `context` so that it will be executed within +that context. Remove it by calling `Source::destroy`. +## `context` +a `MainContext` (if `None`, the default context will be used) + +# Returns + +the ID (greater than 0) for the source within the + `MainContext`. + +Removes a source from its `MainContext`, 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. + +Checks whether a source is allowed to be called recursively. +see `Source::set_can_recurse`. + +# Returns + +whether recursion is allowed. + +Gets the `MainContext` with which the source is associated. + +You can call this on a source that has been destroyed, provided +that the `MainContext` it was attached to still exists (in which +case it will return that `MainContext`). 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 `MainContext` has been destroyed is an error. + +# Returns + +the `MainContext` with which the + source is associated, or `None` if the context has not + yet been added to a source. + +This function ignores `self` and is otherwise the same as +`g_get_current_time`. + +# Deprecated since 2.28 + +use `Source::get_time` instead +## `timeval` +`TimeVal` structure in which to store current time. + +Returns the numeric ID for a particular source. The ID of a source +is a positive integer which is unique within a particular main loop +context. The reverse +mapping from ID to source is done by `MainContext::find_source_by_id`. + +# Returns + +the ID (greater than 0) for the source + +Gets a name for the source, used in debugging and profiling. The +name may be `None` if it has never been set with `Source::set_name`. + +# Returns + +the name of the source + +Gets the priority of a source. + +# Returns + +the priority of the source + +Gets the "ready time" of `self`, as set by +`Source::set_ready_time`. + +Any time before the current monotonic time (including 0) is an +indication that the source will fire immediately. + +# Returns + +the monotonic ready time, -1 for "never" + +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`. + +# Returns + +the monotonic time in microseconds + +Returns whether `self` has been destroyed. + +This is important when you operate upon your objects +from within idle handlers, but may have freed the object +before the dispatch of your idle handler. + + +```C +static gboolean +idle_callback (gpointer data) +{ + SomeWidget *self = data; + + 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. + + +```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; +} +``` + +# Returns + +`true` if the source has been destroyed + +Updates the event mask to watch for the fd identified by `tag`. + +`tag` is the tag returned from `Source::add_unix_fd`. + +If you want to remove a fd, don't set its event mask to zero. +Instead, call `Source::remove_unix_fd`. + +This API is only intended to be used by implementations of `Source`. +Do not call this API on a `Source` that you did not create. + +As the name suggests, this function is not available on Windows. + +Feature: `v2_36` + +## `tag` +the tag from `Source::add_unix_fd` +## `new_events` +the new event mask to watch + +Queries the events reported for the fd corresponding to `tag` on +`self` 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 `self`. + +This API is only intended to be used by implementations of `Source`. +Do not call this API on a `Source` that you did not create. + +As the name suggests, this function is not available on Windows. + +Feature: `v2_36` + +## `tag` +the tag from `Source::add_unix_fd` + +# Returns + +the conditions reported on the fd + +Increases the reference count on a source by one. + +# Returns + +`self` + +Detaches `child_source` from `self` and destroys it. + +This API is only intended to be used by implementations of `Source`. +Do not call this API on a `Source` that you did not create. +## `child_source` +a `Source` previously passed to + `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 `Source`. +Do not call this API on a `Source` that you did not create. +## `fd` +a `PollFD` structure previously passed to `Source::add_poll`. + +Reverses the effect of a previous call to `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 `Source`. +Do not call this API on a `Source` that you did not create. + +As the name suggests, this function is not available on Windows. + +Feature: `v2_36` + +## `tag` +the tag from `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. + +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. +## `func` +a callback function +## `data` +the data to pass to callback function +## `notify` +a function to call when `data` is no longer in use, or `None`. + +Sets the callback function storing the data as a refcounted callback +"object". This is used internally. Note that calling +`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. +## `callback_data` +pointer to callback data "object" +## `callback_funcs` +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. +## `can_recurse` +whether recursion is allowed for this source + +Sets the source functions (can be used to override +default implementations) of an unattached source. +## `funcs` +the new `SourceFuncs` + +Sets a name for the source, used in debugging and profiling. +The name defaults to `None`. + +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 `SourceFuncs` +to include details like the event type in the source name. + +Use caution if changing the name while another thread may be +accessing it with `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. +## `name` +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. +## `priority` +the new priority. + +Sets a `Source` to be dispatched when the given monotonic time is +reached (or passed). If the monotonic time is in the past (as it +always will be if `ready_time` is 0) then the source will be +dispatched immediately. + +If `ready_time` is -1 then the source is never woken up on the basis +of the passage of time. + +Dispatching the source does not reset the ready time. You should do +so yourself, from the source dispatch function. + +Note that if you have a pair of sources where the ready time of one +suggests that it will be delivered first but the priority for the +other suggests that it would be delivered first, and the ready time +for both sources is reached during the same main context iteration +then the order of dispatch is undefined. + +This API is only intended to be used by implementations of `Source`. +Do not call this API on a `Source` that you did not create. + +Feature: `v2_36` + +## `ready_time` +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. + +Removes the source with the given id from the default main context. + +The id of a `Source` is given by `Source::get_id`, or will be +returned by the functions `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`. + +See also `Source::destroy`. You must use `Source::destroy` for sources +added to a non-default main context. + +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. +## `tag` +the ID of the source to remove. + +# Returns + +For historical reasons, this function always returns `true` + +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. +## `funcs` +The `source_funcs` passed to `Source::new` +## `user_data` +the user data for the callback + +# Returns + +`true` if a source was found and removed. + +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. +## `user_data` +the user_data for the callback. + +# Returns + +`true` if a source was found and removed. + +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. +## `tag` +a `Source` ID +## `name` +debug name for the source + +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 + +`TimeZone` is an opaque structure whose members cannot be accessed +directly. + +Creates a `TimeZone` 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 `None`). + +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). + +`TimeZone::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 `None` 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 `TimeZone::unref` +when you are done with it. +## `identifier` +a timezone identifier + +# Returns + +the requested timezone + +Creates a `TimeZone` 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 `TimeZone::new` with the value of +the `TZ` environment variable (including the possibility of `None`). + +You should release the return value by calling `TimeZone::unref` +when you are done with it. + +# Returns + +the local timezone + +Creates a `TimeZone` corresponding to UTC. + +This is equivalent to calling `TimeZone::new` with a value like +"Z", "UTC", "+00", etc. + +You should release the return value by calling `TimeZone::unref` +when you are done with it. + +# Returns + +the universal timezone + +Finds an interval within `self` 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 `TimeZone::find_interval`, with the +difference that it always succeeds (by making the adjustments +described below). + +In any of the cases where `TimeZone::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. +## `type_` +the `TimeType` of `time_` +## `time_` +a pointer to a number of seconds since January 1, 1970 + +# Returns + +the interval containing `time_`, never -1 + +Finds an the interval within `self` that corresponds to the given `time_`. +The meaning of `time_` depends on `type_`. + +If `type_` is `TimeType::Universal` then this function will always +succeed (since universal time is monotonic and continuous). + +Otherwise `time_` is treated as local time. The distinction between +`TimeType::Standard` and `TimeType::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. +## `type_` +the `TimeType` of `time_` +## `time_` +a number of seconds since January 1, 1970 + +# Returns + +the interval containing `time_`, or -1 in case of failure + +Determines the time zone abbreviation to be used during a particular +`interval` of time in the time zone `self`. + +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. +## `interval` +an interval within the timezone + +# Returns + +the time zone abbreviation, which belongs to `self` + +Determines the offset to UTC in effect during a particular `interval` +of time in the time zone `self`. + +The offset is the number of seconds that you add to UTC time to +arrive at local time for `self` (ie: negative numbers for time zones +west of GMT, positive numbers for east). +## `interval` +an interval within the timezone + +# Returns + +the number of seconds that should be added to UTC to get the + local time in `self` + +Determines if daylight savings time is in effect during a particular +`interval` of time in the time zone `self`. +## `interval` +an interval within the timezone + +# Returns + +`true` if daylight savings time is in effect + +Increases the reference count on `self`. + +# Returns + +a new reference to `self`. + +Decreases the reference count on `self`. + +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 `UserDirectory` 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 + +`Variant` is a variant datatype; it can contain one or more values +along with information about the type of the values. + +A `Variant` 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 `Variant` 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 `Variant`, 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 `Variant` holding an integer value you +can use: + + +```C + GVariant *v = g_variant_new ('u', 40); +``` + +The string 'u' in the first argument tells `Variant` that the data passed to +the constructor (40) is going to be an unsigned integer. + +More advanced examples of `Variant` 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 `Variant` is `VariantType`. + +`Variant` instances always have a type and a value (which are given +at construction time). The type and value of a `Variant` instance +can never change other than by the `Variant` itself being +destroyed. A `Variant` cannot contain a pointer. + +`Variant` is reference counted using `Variant::ref` and +`Variant::unref`. `Variant` also has floating reference counts -- +see `Variant::ref_sink`. + +`Variant` is completely threadsafe. A `Variant` instance can be +concurrently accessed in any way from any number of threads without +problems. + +`Variant` 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 `Variant` data can also be sent over the network. + +`Variant` is largely compatible with D-Bus. Almost all types of +`Variant` instances can be sent over D-Bus. See `VariantType` for +exceptions. (However, `Variant`'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 `Variant` 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 `Variant`'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 `MappedFile`, and call `Variant::new_from_data` on it. + +For convenience to C programmers, `Variant` 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 `Variant` +values. `Variant` includes a printer for this language and a parser +with type inferencing. + +## Memory Use + +`Variant` 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 `Variant` can be grouped into 4 broad +purposes: memory for serialised data, memory for the type +information cache, buffer management memory and memory for the +`Variant` 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 `Variant` 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 +`Variant`. + +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 `HashTable` to +store and lookup 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 + +`Variant` 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 +`Variant`. This may involve a `g_free` or a `g_slice_free` or +even `MappedFile::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 `Variant` structure is 6 * (void *). On 32-bit +systems, that's 24 bytes. + +`Variant` structures only exist if they are explicitly created +with API calls. For example, if a `Variant` 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 `Variant` instance exists -- the one referring to the +dictionary. + +If calls are made to start accessing the other values then +`Variant` instances will exist for those values only for as long +as they are in use (ie: until you call `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 byes of memory +for the serialised data, 16 bytes for buffer management and 24 +bytes for the `Variant` instance, or a total of 160 bytes, plus +malloc overhead. If we were to use `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 `Variant` 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 `Variant` 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]. + + +```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); +``` +## `format_string` +a `Variant` format string + +# Returns + +a new floating `Variant` instance + +Creates a new `Variant` array from `children`. + +`child_type` must be non-`None` 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-`None` 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 `None`. + +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 `Variant::ref_sink`), the +new instance takes ownership of them as if via `Variant::ref_sink`. +## `child_type` +the element type of the new array +## `children` +an array of + `Variant` pointers, the children +## `n_children` +the length of `children` + +# Returns + +a floating reference to a new `Variant` array + +Creates a new boolean `Variant` instance -- either `true` or `false`. +## `value` +a `gboolean` value + +# Returns + +a floating reference to a new boolean `Variant` instance + +Creates a new byte `Variant` instance. +## `value` +a `guint8` value + +# Returns + +a floating reference to a new byte `Variant` instance + +Creates an array-of-bytes `Variant` with the contents of `string`. +This function is just like `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. +## `string` +a normal + nul-terminated string in no particular encoding + +# Returns + +a floating reference to a new bytestring `Variant` instance + +Constructs an array of bytestring `Variant` from the given array of +strings. + +If `length` is -1 then `strv` is `None`-terminated. +## `strv` +an array of strings +## `length` +the length of `strv`, or -1 + +# Returns + +a new floating `Variant` instance + +Creates a new dictionary entry `Variant`. `key` and `value` must be +non-`None`. `key` must be a value of a basic type (ie: not a container). + +If the `key` or `value` are floating references (see `Variant::ref_sink`), +the new instance takes ownership of them as if via `Variant::ref_sink`. +## `key` +a basic `Variant`, the key +## `value` +a `Variant`, the value + +# Returns + +a floating reference to a new dictionary entry `Variant` + +Creates a new double `Variant` instance. +## `value` +a `gdouble` floating point value + +# Returns + +a floating reference to a new double `Variant` 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. +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-`None` is set equal to the number of +items in the array. +## `element_type` +the `VariantType` of each element +## `elements` +a pointer to the fixed array of contiguous elements +## `n_elements` +the number of elements +## `element_size` +the size of each element + +# Returns + +a floating reference to a new array `Variant` instance + +Constructs a new serialised-mode `Variant` 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`. + +Feature: `v2_36` + +## `type_` +a `VariantType` +## `bytes` +a `Bytes` +## `trusted` +if the contents of `bytes` are trusted + +# Returns + +a new `Variant` with a floating reference + +Creates a new `Variant` instance from serialised data. + +`type_` is the type of `Variant` 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. `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. +## `type_` +a definite `VariantType` +## `data` +the serialised data +## `size` +the size of `data` +## `trusted` +`true` if `data` is definitely in normal form +## `notify` +function to call when `data` is no longer needed +## `user_data` +data for `notify` + +# Returns + +a new floating `Variant` of type `type_` + +Creates a new handle `Variant` 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. +## `value` +a `gint32` value + +# Returns + +a floating reference to a new handle `Variant` instance + +Creates a new int16 `Variant` instance. +## `value` +a `gint16` value + +# Returns + +a floating reference to a new int16 `Variant` instance + +Creates a new int32 `Variant` instance. +## `value` +a `gint32` value + +# Returns + +a floating reference to a new int32 `Variant` instance + +Creates a new int64 `Variant` instance. +## `value` +a `gint64` value + +# Returns + +a floating reference to a new int64 `Variant` instance + +Depending on if `child` is `None`, 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-`None`. +If `child_type` is non-`None` then it must be a definite type. +If they are both non-`None` then `child_type` must be the type +of `child`. + +If `child` is a floating reference (see `Variant::ref_sink`), the new +instance takes ownership of `child`. +## `child_type` +the `VariantType` of the child, or `None` +## `child` +the child value, or `None` + +# Returns + +a floating reference to a new `Variant` maybe instance + +Creates a D-Bus object path `Variant` with the contents of `string`. +`string` must be a valid D-Bus object path. Use +`Variant::is_object_path` if you're not sure. +## `object_path` +a normal C nul-terminated string + +# Returns + +a floating reference to a new object path `Variant` instance + +Constructs an array of object paths `Variant` from the given array of +strings. + +Each string must be a valid `Variant` object path; see +`Variant::is_object_path`. + +If `length` is -1 then `strv` is `None`-terminated. +## `strv` +an array of strings +## `length` +the length of `strv`, or -1 + +# Returns + +a new floating `Variant` instance + +Parses `format` and returns the result. + +`format` must be a text format `Variant` with one extension: at any +point that a value may appear in the text, a '%' character followed +by a GVariant format string (as per `Variant::new`) may appear. In +that case, the same arguments are collected from the argument list as +`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: + +```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 + +```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 `Variant::parse`. + +You may not use this function to return, unmodified, a single +`Variant` pointer from the argument list. ie: `format` may not solely +be anything along the lines of "%*", "%?", "\%r", or anything starting +with "%@". +## `format` +a text format `Variant` + +# Returns + +a new floating `Variant` instance + +Parses `format` and returns the result. + +This is the version of `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 `Variant` pointer (eg: `format` was "%*") then the collected +`Variant` 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 `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 `Variant::new` call. +## `format` +a text format `Variant` +## `app` +a pointer to a `va_list` + +# Returns + +a new, usually floating, `Variant` + +Creates a string-type GVariant using printf formatting. + +This is similar to calling `g_strdup_printf` and then +`Variant::new_string` but it saves a temporary variable and an +unnecessary copy. + +Feature: `v2_38` + +## `format_string` +a printf-style format string + +# Returns + +a floating reference to a new string + `Variant` instance + +Creates a D-Bus type signature `Variant` with the contents of +`string`. `string` must be a valid D-Bus type signature. Use +`Variant::is_signature` if you're not sure. +## `signature` +a normal C nul-terminated string + +# Returns + +a floating reference to a new signature `Variant` instance + +Creates a string `Variant` with the contents of `string`. + +`string` must be valid UTF-8, and must not be `None`. To encode +potentially-`None` strings, use `Variant::new` with `ms` as the +[format string][gvariant-format-strings-maybe-types]. +## `string` +a normal UTF-8 nul-terminated string + +# Returns + +a floating reference to a new string `Variant` instance + +Constructs an array of strings `Variant` from the given array of +strings. + +If `length` is -1 then `strv` is `None`-terminated. +## `strv` +an array of strings +## `length` +the length of `strv`, or -1 + +# Returns + +a new floating `Variant` instance + +Creates a string `Variant` with the contents of `string`. + +`string` must be valid UTF-8, and must not be `None`. To encode +potentially-`None` strings, use this with `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. + +Feature: `v2_38` + +## `string` +a normal UTF-8 nul-terminated string + +# Returns + +a floating reference to a new string + `Variant` instance + +Creates a new tuple `Variant` out of the items in `children`. The +type is determined from the types of `children`. No entry in the +`children` array may be `None`. + +If `n_children` is 0 then the unit tuple is constructed. + +If the `children` are floating references (see `Variant::ref_sink`), the +new instance takes ownership of them as if via `Variant::ref_sink`. +## `children` +the items to make the tuple out of +## `n_children` +the length of `children` + +# Returns + +a floating reference to a new `Variant` tuple + +Creates a new uint16 `Variant` instance. +## `value` +a `guint16` value + +# Returns + +a floating reference to a new uint16 `Variant` instance + +Creates a new uint32 `Variant` instance. +## `value` +a `guint32` value + +# Returns + +a floating reference to a new uint32 `Variant` instance + +Creates a new uint64 `Variant` instance. +## `value` +a `guint64` value + +# Returns + +a floating reference to a new uint64 `Variant` instance + +This function is intended to be used by libraries based on +`Variant` that want to provide `Variant::new`-like functionality +to their users. + +The API is more general than `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 `None`. If `endptr` is +non-`None` 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 +`Variant::new_va` and `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 `Variant` 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 `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 `Variant::new` call. +## `format_string` +a string that is prefixed with a format string +## `endptr` +location to store the end pointer, + or `None` +## `app` +a pointer to a `va_list` + +# Returns + +a new, usually floating, `Variant` + +Boxes `value`. The result is a `Variant` instance representing a +variant containing the original value. + +If `child` is a floating reference (see `Variant::ref_sink`), the new +instance takes ownership of `child`. +## `value` +a `Variant` instance + +# Returns + +a floating reference to a new variant `Variant` instance + +Performs a byteswapping operation on the contents of `self`. The +result is that all multi-byte numeric data contained in `self` 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. + +# Returns + +the byteswapped form of `self` + +Checks if calling `Variant::get` with `format_string` on `self` 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 `Variant::unref` on `self` immediately after +the call to `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 `Variant` 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 `Variant` values of uncertain values (eg: +`Variant::lookup` or `g_menu_model_get_item_attribute`). + +Feature: `v2_34` + +## `format_string` +a valid `Variant` format string +## `copy_only` +`true` to ensure the format string makes deep copies + +# Returns + +`true` if `format_string` is safe to use + +Classifies `self` according to its top-level type. + +# Returns + +the `VariantClass` of `self` + +Compares `self` and `two`. + +The types of `self` and `two` are `gconstpointer` only to allow use of +this function with `Tree`, `PtrArray`, etc. They must each be a +`Variant`. + +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, `Variant::equal` is more +general. +## `two` +a `Variant` instance of the same type + +# Returns + +negative value if a < b; + zero if a = b; + positive value if a > b. + +Similar to `Variant::get_bytestring` except that instead of +returning a constant string, the string is duplicated. + +The return value must be freed using `g_free`. +## `length` +a pointer to a `gsize`, to store + the length (not including the nul terminator) + +# Returns + + + a newly allocated string + +Gets the contents of an array of array of bytes `Variant`. This call +makes a deep copy; the return result should be released with +`g_strfreev`. + +If `length` is non-`None` then the number of elements in the result is +stored there. In any case, the resulting array will be +`None`-terminated. + +For an empty array, `length` will be set to 0 and a pointer to a +`None` pointer will be returned. +## `length` +the length of the result, or `None` + +# Returns + +an array of strings + +Gets the contents of an array of object paths `Variant`. This call +makes a deep copy; the return result should be released with +`g_strfreev`. + +If `length` is non-`None` then the number of elements in the result +is stored there. In any case, the resulting array will be +`None`-terminated. + +For an empty array, `length` will be set to 0 and a pointer to a +`None` pointer will be returned. +## `length` +the length of the result, or `None` + +# Returns + +an array of strings + +Similar to `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`. +## `length` +a pointer to a `gsize`, to store the length + +# Returns + +a newly allocated string, UTF-8 encoded + +Gets the contents of an array of strings `Variant`. This call +makes a deep copy; the return result should be released with +`g_strfreev`. + +If `length` is non-`None` then the number of elements in the result +is stored there. In any case, the resulting array will be +`None`-terminated. + +For an empty array, `length` will be set to 0 and a pointer to a +`None` pointer will be returned. +## `length` +the length of the result, or `None` + +# Returns + +an array of strings + +Checks if `self` and `two` have the same type and value. + +The types of `self` and `two` are `gconstpointer` only to allow use of +this function with `HashTable`. They must each be a `Variant`. +## `two` +a `Variant` instance + +# Returns + +`true` if `self` and `two` are equal + +Deconstructs a `Variant` 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 `self`. 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]. +## `format_string` +a `Variant` format string + +Returns the boolean value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_BOOLEAN`. + +# Returns + +`true` or `false` + +Returns the byte value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_BYTE`. + +# Returns + +a `guchar` + +Returns the string value of a `Variant` 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-`None` 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. + +`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 `self` that is not an +array of bytes. + +The return value remains valid as long as `self` exists. + +# Returns + + + the constant string + +Gets the contents of an array of array of bytes `Variant`. 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-`None` then the number of elements in the result is +stored there. In any case, the resulting array will be +`None`-terminated. + +For an empty array, `length` will be set to 0 and a pointer to a +`None` pointer will be returned. +## `length` +the length of the result, or `None` + +# Returns + +an array of constant strings + +Reads a child item out of a container `Variant` instance and +deconstructs it according to `format_string`. This call is +essentially a combination of `Variant::get_child_value` and +`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]. +## `index_` +the index of the child to deconstruct +## `format_string` +a `Variant` format string + +Reads a child item out of a container `Variant` instance. This +includes variants, maybes, arrays, tuples and dictionary +entries. It is an error to call this function on any other type of +`Variant`. + +It is an error if `index_` is greater than the number of child items +in the container. See `Variant::n_children`. + +The returned value is never floating. You should free it with +`Variant::unref` when you're done with it. + +This function is O(1). +## `index_` +the index of the child to fetch + +# Returns + +the child at the specified index + +Returns a pointer to the serialised form of a `Variant` 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 `self` exists. + +If `self` is a fixed-sized value that was deserialised from a +corrupted serialised container then `None` may be returned. In this +case, the proper thing to do is typically to use the appropriate +number of nul bytes in place of `self`. If `self` is not fixed-sized +then `None` is never returned. + +In the case that `self` 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 `Variant`, 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). + +# Returns + +the serialised form of `self`, or `None` + +Returns a pointer to the serialised form of a `Variant` instance. +The semantics of this function are exactly the same as +`Variant::get_data`, except that the returned `Bytes` holds +a reference to the variant data. + +Feature: `v2_36` + + +# Returns + +A new `Bytes` representing the variant data + +Returns the double precision floating point value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_DOUBLE`. + +# Returns + +a `gdouble` + +Provides access to the serialised data for an array of fixed-sized +items. + +`self` 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`: `guchar` +- `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-`None` is set equal to the number of +items in the array. +## `n_elements` +a pointer to the location to store the number of items +## `element_size` +the size of each element + +# Returns + +a pointer to + the fixed array + +Returns the 32-bit signed integer value of `self`. + +It is an error to call this function with a `self` 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. + +# Returns + +a `gint32` + +Returns the 16-bit signed integer value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_INT16`. + +# Returns + +a `gint16` + +Returns the 32-bit signed integer value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_INT32`. + +# Returns + +a `gint32` + +Returns the 64-bit signed integer value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_INT64`. + +# Returns + +a `gint64` + +Given a maybe-typed `Variant` instance, extract its value. If the +value is Nothing, then this function returns `None`. + +# Returns + +the contents of `self`, or `None` + +Gets a `Variant` instance that has the same value as `self` and is +trusted to be in normal form. + +If `self` is already trusted to be in normal form then a new +reference to `self` is returned. + +If `self` 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 `self` is found not to be in normal form then a new trusted +`Variant` is created with the same value as `self`. + +It makes sense to call this function if you've received `Variant` +data from untrusted sources and you want to ensure your serialised +output is definitely in normal form. + +# Returns + +a trusted `Variant` + +Gets the contents of an array of object paths `Variant`. 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-`None` then the number of elements in the result +is stored there. In any case, the resulting array will be +`None`-terminated. + +For an empty array, `length` will be set to 0 and a pointer to a +`None` pointer will be returned. +## `length` +the length of the result, or `None` + +# Returns + +an array of constant strings + +Determines the number of bytes that would be required to store `self` +with `Variant::store`. + +If `self` has a fixed-sized type then this function always returned +that fixed size. + +In the case that `self` 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. + +# Returns + +the serialised size of `self` + +Returns the string value of a `Variant` 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 `None`. + +If `length` is non-`None` 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 `self` of any type +other than those three. + +The return value remains valid as long as `self` exists. +## `length` +a pointer to a `gsize`, + to store the length + +# Returns + +the constant string, UTF-8 encoded + +Gets the contents of an array of strings `Variant`. 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-`None` then the number of elements in the result +is stored there. In any case, the resulting array will be +`None`-terminated. + +For an empty array, `length` will be set to 0 and a pointer to a +`None` pointer will be returned. +## `length` +the length of the result, or `None` + +# Returns + +an array of constant strings + +Determines the type of `self`. + +The return value is valid for the lifetime of `self` and must not +be freed. + +# Returns + +a `VariantType` + +Returns the type string of `self`. Unlike the result of calling +`VariantType::peek_string`, this string is nul-terminated. This +string belongs to `Variant` and must not be freed. + +# Returns + +the type string for the type of `self` + +Returns the 16-bit unsigned integer value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_UINT16`. + +# Returns + +a `guint16` + +Returns the 32-bit unsigned integer value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_UINT32`. + +# Returns + +a `guint32` + +Returns the 64-bit unsigned integer value of `self`. + +It is an error to call this function with a `self` of any type +other than `G_VARIANT_TYPE_UINT64`. + +# Returns + +a `guint64` + +This function is intended to be used by libraries based on `Variant` +that want to provide `Variant::get`-like functionality to their +users. + +The API is more general than `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 `None`. If `endptr` is +non-`None` 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 +`Variant::new_va` and `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]. +## `format_string` +a string that is prefixed with a format string +## `endptr` +location to store the end pointer, + or `None` +## `app` +a pointer to a `va_list` + +Unboxes `self`. The result is the `Variant` instance that was +contained in `self`. + +# Returns + +the item contained in the variant + +Generates a hash value for a `Variant` 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 `self` is `gconstpointer` only to allow use of this +function with `HashTable`. `self` must be a `Variant`. + +# Returns + +a hash value corresponding to `self` + +Checks if `self` is a container. + +# Returns + +`true` if `self` is a container + +Checks whether `self` 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 `Variant::ref_sink` +or `Variant::take_ref`. + +See `Variant::ref_sink` for more information about floating reference +counts. + +# Returns + +whether `self` is floating + +Checks if `self` 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 `Variant` +using `Variant::new_from_data` and then use this function to +check. + +If `self` 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`. + +# Returns + +`true` if `self` is in normal form + +Checks if a value has a type matching the provided type. +## `type_` +a `VariantType` + +# Returns + +`true` if the type of `self` matches `type_` + +Creates a heap-allocated `VariantIter` for iterating over the items +in `self`. + +Use `VariantIter::free` to free the return value when you no longer +need it. + +A reference is taken to `self` and will be released only when +`VariantIter::free` is called. + +# Returns + +a new heap-allocated `VariantIter` + +Looks up a value in a dictionary `Variant`. + +This function is a wrapper around `Variant::lookup_value` and +`Variant::get`. In the case that `None` 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 `VariantDict` may be more efficient. +## `key` +the key to lookup in the dictionary +## `format_string` +a GVariant format string + +# Returns + +`true` if a value was unpacked + +Looks up a value in a dictionary `Variant`. + +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 `self` 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 +`None` is returned. In the event that `self` has a value type other +than v then `expected_type` must directly match the key type and it is +used to unpack the value directly or an error occurs. + +In either case, if `key` is not found in `self`, `None` 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-`None` return +value will have this type. + +This function is currently implemented with a linear scan. If you +plan to do many lookups then `VariantDict` may be more efficient. +## `key` +the key to lookup in the dictionary +## `expected_type` +a `VariantType`, or `None` + +# Returns + +the value of the dictionary key, or `None` + +Determines the number of children in a container `Variant` instance. +This includes variants, maybes, arrays, tuples and dictionary +entries. It is an error to call this function on any other type of +`Variant`. + +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). + +# Returns + +the number of children in the container + +Pretty-prints `self` in the format understood by `Variant::parse`. + +The format is described [here][gvariant-text]. + +If `type_annotate` is `true`, then type information is included in +the output. +## `type_annotate` +`true` if type information should be included in + the output + +# Returns + +a newly-allocated string holding the result. + +Behaves as `Variant::print`, but operates on a `String`. + +If `string` is non-`None` then it is appended to and returned. Else, +a new empty `String` is allocated and it is returned. +## `string` +a `String`, or `None` +## `type_annotate` +`true` if type information should be included in + the output + +# Returns + +a `String` containing the string + +Increases the reference count of `self`. + +# Returns + +the same `self` + +`Variant` uses a floating reference count system. All functions with +names starting with `g_variant_new_` return floating +references. + +Calling `Variant::ref_sink` on a `Variant` with a floating reference +will convert the floating reference into a full reference. Calling +`Variant::ref_sink` on a non-floating `Variant` results in an +additional normal reference being added. + +In other words, if the `self` is floating, then this call "assumes +ownership" of the floating reference, converting it to a normal +reference. If the `self` is not floating, then this call adds a +new normal reference increasing the reference count by one. + +All calls that result in a `Variant` instance being inserted into a +container will call `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. + +# Returns + +the same `self` + +Stores the serialised form of `self` at `data`. `data` should be +large enough. See `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 +`Variant::get_normal_form` for a solution. + +As with `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`. +## `data` +the location to store the serialised data at + +If `self` is floating, sink it. Otherwise, do nothing. + +Typically you want to use `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 +`Variant`. 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 `Variant` API makes it likely that +for newly-created `Variant` instances, the user can be saved some +typing if they are allowed to return a `Variant` 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 +`Variant::ref_sink` running at the same time in another thread on +the same `Variant` instance. If `Variant::ref_sink` runs first then +the result will be that the floating reference is converted to a hard +reference. If `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. + +# Returns + +the same `self` + +Decreases the reference count of `self`. When its reference count +drops to 0, the memory used by the variant is freed. + +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 `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. +## `string` +a normal C nul-terminated string + +# Returns + +`true` if `string` is a D-Bus object path + +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 `Variant::new_signature`. + +D-Bus type signatures consist of zero or more definite `VariantType` +strings in sequence. +## `string` +a normal C nul-terminated string + +# Returns + +`true` if `string` is a D-Bus type signature + +Parses a `Variant` from a text representation. + +A single `Variant` 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-`None` 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 `None` and there is extra data +then an error is returned. + +If `type_` is non-`None` 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 `Variant` +is returned. It is never floating, and must be freed with +`Variant::unref`. + +In case of any error, `None` will be returned. If `error` is non-`None` +then it will be set to reflect the error that occurred. + +Officially, the language understood by the parser is "any string +produced by `Variant::print`". +## `type_` +a `VariantType`, or `None` +## `text` +a string containing a GVariant in text form +## `limit` +a pointer to the end of `text`, or `None` +## `endptr` +a location to store the end pointer, or `None` + +# Returns + +a non-floating reference to a `Variant`, or `None` + +Pretty-prints a message showing the context of a `Variant` 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: + + +```text +unterminated string constant: + (1, 2, 3, 'abc + ^^^^ +``` + +or + + +```text +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 `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 +`Variant::parse` then you must add nul termination before using this +function. + +Feature: `v2_40` + +## `error` +a `Error` from the `VariantParseError` domain +## `source_str` +the string that was given to the parser + +# Returns + +the printed message + +Same as `g_variant_error_quark`. + +# Deprecated + +Use `Variant::parse_error_quark` instead. + +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, +`Variant::get_type` will never return an indefinite type, but +calling `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 +`VariantType::is_basic`) and is always a single character in length. +The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", +"h", "d", "s", "o", "g" and "?". + +The above definition is recursive to arbitrary depth. "aaaaai" and +"(ui(nq((y)))s)" are both valid type strings, as is +"a(aa(ui)(qna{ya(yd)}))". + +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_STRING`; 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 `VariantType` corresponding to the type string given +by `type_string`. It is appropriate to call `VariantType::free` on +the return value. + +It is a programmer error to call this function with an invalid type +string. Use `VariantType::string_is_valid` if you are unsure. +## `type_string` +a valid GVariant type string + +# Returns + +a new `VariantType` + +Constructs the type corresponding to an array of elements of the +type `type_`. + +It is appropriate to call `VariantType::free` on the return value. +## `element` +a `VariantType` + +# Returns + +a new array `VariantType` + +Since 2.24 + +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 `VariantType::free` on the return value. +## `key` +a basic `VariantType` +## `value` +a `VariantType` + +# Returns + +a new dictionary entry `VariantType` + +Since 2.24 + +Constructs the type corresponding to a maybe instance containing +type `type_` or Nothing. + +It is appropriate to call `VariantType::free` on the return value. +## `element` +a `VariantType` + +# Returns + +a new maybe `VariantType` + +Since 2.24 + +Constructs a new tuple type, from `items`. + +`length` is the number of items in `items`, or -1 to indicate that +`items` is `None`-terminated. + +It is appropriate to call `VariantType::free` on the return value. +## `items` +an array of `GVariantTypes`, one for each item +## `length` +the length of `items`, or -1 + +# Returns + +a new tuple `VariantType` + +Since 2.24 + +Makes a copy of a `VariantType`. It is appropriate to call +`VariantType::free` on the return value. `self` may not be `None`. + +# Returns + +a new `VariantType` + +Since 2.24 + +Returns a newly-allocated copy of the type string corresponding to +`self`. The returned string is nul-terminated. It is appropriate to +call `g_free` on the return value. + +# Returns + +the corresponding type string + +Since 2.24 + +Determines the element type of an array or maybe type. + +This function may only be used with array or maybe types. + +# Returns + +the element type of `self` + +Since 2.24 + +Compares `self` 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 `VariantType::is_subtype_of`. + +The argument types of `self` and `type2` are only `gconstpointer` to +allow use with `HashTable` without function pointer casting. For +both arguments, a valid `VariantType` must be provided. +## `type2` +a `VariantType` + +# Returns + +`true` if `self` and `type2` are exactly equal + +Since 2.24 + +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. + +`None` is returned in case of `self` being `G_VARIANT_TYPE_UNIT`. + +This call, together with `VariantType::next` provides an iterator +interface over tuple and dictionary entry types. + +# Returns + +the first item type of `self`, or `None` + +Since 2.24 + +Frees a `VariantType` that was allocated with +`VariantType::copy`, `VariantType::new` or one of the container +type constructor functions. + +In the case that `self` is `None`, this function does nothing. + +Since 2.24 + +Returns the length of the type string corresponding to the given +`self`. This function must be used to determine the valid extent of +the memory region returned by `VariantType::peek_string`. + +# Returns + +the length of the corresponding type string + +Since 2.24 + +Hashes `self`. + +The argument type of `self` is only `gconstpointer` to allow use with +`HashTable` without function pointer casting. A valid +`VariantType` must be provided. + +# Returns + +the hash value + +Since 2.24 + +Determines if the given `self` is an array type. This is true if the +type string for `self` 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. + +# Returns + +`true` if `self` is an array type + +Since 2.24 + +Determines if the given `self` 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`. + +# Returns + +`true` if `self` is a basic type + +Since 2.24 + +Determines if the given `self` 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. + +# Returns + +`true` if `self` is a container type + +Since 2.24 + +Determines if the given `self` is definite (ie: not indefinite). + +A type is definite if its type string does not contain any indefinite +type characters ('*', '?', or 'r'). + +A `Variant` instance may not have an indefinite type, so calling +this function on the result of `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. + +# Returns + +`true` if `self` is definite + +Since 2.24 + +Determines if the given `self` is a dictionary entry type. This is +true if the type string for `self` 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. + +# Returns + +`true` if `self` is a dictionary entry type + +Since 2.24 + +Determines if the given `self` is a maybe type. This is true if the +type string for `self` 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. + +# Returns + +`true` if `self` is a maybe type + +Since 2.24 + +Checks if `self` is a subtype of `supertype`. + +This function returns `true` if `self` is a subtype of `supertype`. All +types are considered to be subtypes of themselves. Aside from that, +only indefinite types can have subtypes. +## `supertype` +a `VariantType` + +# Returns + +`true` if `self` is a subtype of `supertype` + +Since 2.24 + +Determines if the given `self` is a tuple type. This is true if the +type string for `self` starts with a '(' or if `self` 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. + +# Returns + +`true` if `self` is a tuple type + +Since 2.24 + +Determines if the given `self` is the variant type. + +# Returns + +`true` if `self` is the variant type + +Since 2.24 + +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 +`VariantType::first`. + +# Returns + +the key type of the dictionary entry + +Since 2.24 + +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. + +# Returns + +the number of items in `self` + +Since 2.24 + +Determines the next item type of a tuple or dictionary entry +type. + +`self` must be the result of a previous call to +`VariantType::first` or `VariantType::next`. + +If called on the key type of a dictionary entry then this call +returns the value type. If called on the value type of a dictionary +entry then this call returns `None`. + +For tuples, `None` is returned when `self` is the last item in a tuple. + +# Returns + +the next `VariantType` after `self`, or `None` + +Since 2.24 + +Returns the type string corresponding to the given `self`. The +result is not nul-terminated; in order to determine its length you +must call `VariantType::get_string_length`. + +To get a nul-terminated string, see `VariantType::dup_string`. + +# Returns + +the corresponding type string (not nul-terminated) + +Since 2.24 + +Determines the value type of a dictionary entry type. + +This function may only be used with a dictionary entry type. + +# Returns + +the value type of the dictionary entry + +Since 2.24 + +Checks if `type_string` is a valid GVariant type string. This call is +equivalent to calling `VariantType::string_scan` and confirming +that the following character is a nul terminator. +## `type_string` +a pointer to any string + +# Returns + +`true` if `type_string` is exactly one valid type string + +Since 2.24 + +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 `VariantType::string_is_valid`. +## `string` +a pointer to any string +## `limit` +the end of `string`, or `None` +## `endptr` +location to store the end pointer, or `None` + +# Returns + +`true` if a valid type string was found diff --git a/gtk/vendor.md b/gtk/vendor.md index de7847b6..2057b59f 100644 --- a/gtk/vendor.md +++ b/gtk/vendor.md @@ -35,25 +35,31 @@ gtk_show_about_dialog (NULL, ``` It is also possible to show a `AboutDialog` like any other `Dialog`, -e.g. using `Dialog::run`. In this case, you might need to know that +e.g. using `DialogExt::run`. In this case, you might need to know that the “Close” button returns the `ResponseType::Cancel` response id. # Implements -[`DialogExt`](trait.DialogExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`AboutDialogExt`](trait.AboutDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `AboutDialog` methods. + +# Implementors + +[`AboutDialog`](struct.AboutDialog.html) Creates a new `AboutDialog`. # Returns a newly created `AboutDialog` - + Creates a new section in the Credits page. ## `section_name` The name of the section ## `people` The people who belong to that section - + Returns the string which are displayed in the artists tab of the secondary credits dialog. @@ -62,7 +68,7 @@ of the secondary credits dialog. A `None`-terminated string array containing the artists. The array is owned by the about dialog and must not be modified. - + Returns the string which are displayed in the authors tab of the secondary credits dialog. @@ -71,21 +77,21 @@ of the secondary credits dialog. A `None`-terminated string array containing the authors. The array is owned by the about dialog and must not be modified. - + Returns the comments string. # Returns The comments. The string is owned by the about dialog and must not be modified. - + Returns the copyright string. # Returns The copyright string. The string is owned by the about dialog and must not be modified. - + Returns the string which are displayed in the documenters tab of the secondary credits dialog. @@ -94,28 +100,28 @@ tab of the secondary credits dialog. A `None`-terminated string array containing the documenters. The array is owned by the about dialog and must not be modified. - + Returns the license information. # Returns The license information. The string is owned by the about dialog and must not be modified. - -Retrieves the license set using `AboutDialog::set_license_type` + +Retrieves the license set using `AboutDialogExt::set_license_type` # Returns a `License` value - + Returns the pixbuf displayed as logo in the about dialog. # Returns 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 `gobject::Object::ref` on it. - + reference to it, you have to call `gobject::ObjectExt::ref` on it. + Returns the icon name displayed as logo in the about dialog. # Returns @@ -123,14 +129,14 @@ 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. - + Returns the program name displayed in the about dialog. # Returns The program name. The string is owned by the about dialog and must not be modified. - + Returns the translator credits string which is displayed in the translators tab of the secondary credits dialog. @@ -138,91 +144,91 @@ 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. - + Returns the version string. # Returns The version string. The string is owned by the about dialog and must not be modified. - + Returns the website URL. # Returns The website URL. The string is owned by the about dialog and must not be modified. - + Returns the label used for the website link. # Returns The label used for the website link. The string is owned by the about dialog and must not be modified. - + Returns whether the license text in `self` is automatically wrapped. # Returns `true` if the license text is wrapped - + Sets the strings which are displayed in the artists tab of the secondary credits dialog. ## `artists` a `None`-terminated array of strings - + Sets the strings which are displayed in the authors tab of the secondary credits dialog. ## `authors` a `None`-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. ## `comments` a comments string - + Sets the copyright string to display in the about dialog. This should be a short string of one or two lines. ## `copyright` the copyright string - + Sets the strings which are displayed in the documenters tab of the secondary credits dialog. ## `documenters` a `None`-terminated array of strings - + Sets the license information to be displayed in the secondary license dialog. If `license` is `None`, the license button is hidden. ## `license` the license information or `None` - + Sets the license of the application showing the `self` dialog from a list of known licenses. This function overrides the license set using -`AboutDialog::set_license`. +`AboutDialogExt::set_license`. ## `license_type` the type of license - + Sets the pixbuf to be displayed as logo in the about dialog. If it is `None`, the default window icon set with `Window::set_default_icon` will be used. ## `logo` a `gdk_pixbuf::Pixbuf`, or `None` - + Sets the pixbuf to be displayed as logo in the about dialog. If it is `None`, the default window icon set with `Window::set_default_icon` will be used. ## `icon_name` an icon name, or `None` - + Sets the name to display in the about dialog. If this is not set, it defaults to `g_get_application_name`. ## `name` the program name - + Sets the translator credits string which is displayed in the translators tab of the secondary credits dialog. @@ -241,19 +247,19 @@ since `AboutDialog` will detect if “translator-credits” is untranslated and hide the tab. ## `translator_credits` the translator credits - + Sets the version string to display in the about dialog. ## `version` the version string - + Sets the URL to use for the website link. ## `website` a URL string starting with "http://" - + Sets the label to be used for the website link. ## `website_label` the label used for the website link - + Sets whether the license text in `self` is automatically wrapped. ## `wrap_license` @@ -261,7 +267,7 @@ whether to wrap the license A `AccelGroup` represents a group of keyboard accelerators, typically attached to a toplevel `Window` (with -`Window::add_accel_group`). Usually you won’t need to create a +`WindowExt::add_accel_group`). Usually you won’t need to create a `AccelGroup` directly; instead, when using `UIManager`, GTK+ automatically sets up the accelerators for your menus in the ui manager’s `AccelGroup`. @@ -277,7 +283,13 @@ and mnemonics, of course. # Implements -[`ObjectExt`](trait.ObjectExt.html) +[`AccelGroupExt`](trait.AccelGroupExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `AccelGroup` methods. + +# Implementors + +[`AccelGroup`](struct.AccelGroup.html) Creates a new `AccelGroup`. @@ -286,7 +298,7 @@ Creates a new `AccelGroup`. a new `AccelGroup` object Finds the `AccelGroup` to which `closure` is connected; -see `AccelGroup::connect`. +see `AccelGroupExt::connect`. ## `closure` a `gobject::Closure` @@ -294,7 +306,7 @@ a `gobject::Closure` the `AccelGroup` to which `closure` is connected, or `None` - + Finds the first accelerator in `self` that matches `accel_key` and `accel_mods`, and activates it. ## `accel_quark` @@ -311,7 +323,7 @@ keyboard state mask from a key event `true` if an accelerator was activated and handled this keypress - + Installs an accelerator in this group. When `self` 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 @@ -329,7 +341,7 @@ modifier combination of the accelerator a flag mask to configure this accelerator ## `closure` 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 `AccelMap::add_entry`). When `self` is being activated @@ -346,9 +358,9 @@ first with `g_intern_static_string`. path used for determining key and modifiers ## `closure` closure to be executed upon accelerator activation - + Removes an accelerator previously installed through -`AccelGroup::connect`. +`AccelGroupExt::connect`. Since 2.20 `closure` can be `None`. ## `closure` @@ -358,9 +370,9 @@ the closure to remove from this accelerator # Returns `true` if the closure was found and got disconnected - + Removes an accelerator previously installed through -`AccelGroup::connect`. +`AccelGroupExt::connect`. ## `accel_key` key value of the accelerator ## `accel_mods` @@ -370,7 +382,7 @@ modifier combination of the accelerator `true` if there was an accelerator which could be removed, `false` otherwise - + Finds the first entry in an accelerator group for which `find_func` returns `true` and returns its `AccelKey`. ## `find_func` @@ -383,22 +395,22 @@ data to pass to `find_func` the key of the first entry passing `find_func`. The key is owned by GTK+ and must not be freed. - -Locks are added and removed using `AccelGroup::lock` and -`AccelGroup::unlock`. + +Locks are added and removed using `AccelGroupExt::lock` and +`AccelGroupExt::unlock`. # Returns `true` if there are 1 or more locks on the `self`, `false` otherwise. - + Gets a `gdk::ModifierType` representing the mask for this `self`. For example, `gdk::ModifierType::ControlMask`, `gdk::ModifierType::ShiftMask`, etc. # Returns the modifier mask for this accel group. - + Locks the given accelerator group. Locking an acelerator group prevents the accelerators contained @@ -406,9 +418,9 @@ within it to be changed during runtime. Refer to `AccelMap::change_entry` about runtime accelerator changes. If called more than once, `self` remains locked until -`AccelGroup::unlock` has been called an equivalent number +`AccelGroupExt::unlock` has been called an equivalent number of times. - + Queries an accelerator group for all entries matching `accel_key` and `accel_mods`. ## `accel_key` @@ -424,8 +436,8 @@ location to return the number an array of `n_entries` `AccelGroupEntry` elements, or `None`. The array is owned by GTK+ and must not be freed. - -Undoes the last call to `AccelGroup::lock` on this `self`. + +Undoes the last call to `AccelGroupExt::lock` on this `self`. `ActionBar` is designed to present contextual actions. It is expected to be displayed below the content and expand horizontally @@ -436,11 +448,23 @@ 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 + +`ActionBar` has a single CSS node with name actionbar. + Feature: `v3_12` # Implements -[`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`ActionBarExt`](trait.ActionBarExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `ActionBar` methods. + +Feature: `v3_12` + +# Implementors + +[`ActionBar`](struct.ActionBar.html) Creates a new `ActionBar` widget. @@ -450,7 +474,7 @@ Feature: `v3_12` # Returns a new `ActionBar` - + Retrieves the center bar widget of the bar. Feature: `v3_12` @@ -458,8 +482,8 @@ Feature: `v3_12` # Returns -the center `Widget`. - +the center `Widget` or `None`. + Adds `child` to `self`, packed with reference to the end of the `self`. @@ -467,7 +491,7 @@ Feature: `v3_12` ## `child` the `Widget` to be added to `self` - + Adds `child` to `self`, packed with reference to the start of the `self`. @@ -475,7 +499,7 @@ Feature: `v3_12` ## `child` the `Widget` to be added to `self` - + Sets the center widget for the `ActionBar`. Feature: `v3_12` @@ -493,8 +517,8 @@ 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 `ApplicationWindow` -or "`Application`, but other action groups that are added with -`Widget::insert_action_group` will be consulted as well. +or `Application`, but other action groups that are added with +`WidgetExt::insert_action_group` will be consulted as well. # Implements @@ -504,7 +528,7 @@ Trait containing all `Actionable` methods. # Implementors -[`Actionable`](struct.Actionable.html), [`Button`](struct.Button.html), [`CheckButton`](struct.CheckButton.html), [`CheckMenuItem`](struct.CheckMenuItem.html), [`ColorButton`](struct.ColorButton.html), [`FontButton`](struct.FontButton.html), [`ImageMenuItem`](struct.ImageMenuItem.html), [`LinkButton`](struct.LinkButton.html), [`MenuButton`](struct.MenuButton.html), [`MenuItem`](struct.MenuItem.html), [`MenuToolButton`](struct.MenuToolButton.html), [`RadioButton`](struct.RadioButton.html), [`ScaleButton`](struct.ScaleButton.html), [`SeparatorMenuItem`](struct.SeparatorMenuItem.html), [`Switch`](struct.Switch.html), [`ToggleButton`](struct.ToggleButton.html), [`ToggleToolButton`](struct.ToggleToolButton.html), [`ToolButton`](struct.ToolButton.html), [`VolumeButton`](struct.VolumeButton.html) +[`Actionable`](struct.Actionable.html), [`Button`](struct.Button.html), [`CheckButton`](struct.CheckButton.html), [`CheckMenuItem`](struct.CheckMenuItem.html), [`ColorButton`](struct.ColorButton.html), [`FontButton`](struct.FontButton.html), [`ImageMenuItem`](struct.ImageMenuItem.html), [`LinkButton`](struct.LinkButton.html), [`MenuButton`](struct.MenuButton.html), [`MenuItem`](struct.MenuItem.html), [`MenuToolButton`](struct.MenuToolButton.html), [`ModelButton`](struct.ModelButton.html), [`RadioButton`](struct.RadioButton.html), [`RadioMenuItem`](struct.RadioMenuItem.html), [`ScaleButton`](struct.ScaleButton.html), [`SeparatorMenuItem`](struct.SeparatorMenuItem.html), [`Switch`](struct.Switch.html), [`ToggleButton`](struct.ToggleButton.html), [`ToggleToolButton`](struct.ToggleToolButton.html), [`ToolButton`](struct.ToolButton.html), [`VolumeButton`](struct.VolumeButton.html) Gets the action name for `self`. @@ -514,7 +538,7 @@ See `Actionable::set_action_name` for more information. the action name, or `None` if none is set -Gets the current target value of `actionabe`. +Gets the current target value of `self`. See `Actionable::set_action_target_value` for more information. @@ -586,60 +610,67 @@ the detailed action name The `Adjustment` 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 -`SpinButton`, `Viewport`, and `Range` (which is a base class for -`HScrollbar`, `VScrollbar`, `HScale`, and `VScale`). +It is used within several GTK+ widgets, including `SpinButton`, `Viewport`, +and `Range` (which is a base class for `Scrollbar` and `Scale`). The `Adjustment` object does not update the value itself. Instead it is left up to the owner of the `Adjustment` to control the value. -The owner of the `Adjustment` typically calls the -`Adjustment::value_changed` and `Adjustment::changed` functions -after changing the value and its bounds. This results in the emission of the -`Adjustment::value_changed` or `Adjustment::changed` signal respectively. - # Implements -[`ObjectExt`](trait.ObjectExt.html) +[`AdjustmentExt`](trait.AdjustmentExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Adjustment` methods. + +# Implementors + +[`Adjustment`](struct.Adjustment.html) Creates a new `Adjustment`. ## `value` -the initial value. +the initial value ## `lower` -the minimum value. +the minimum value ## `upper` -the maximum value. +the maximum value ## `step_increment` -the step increment. +the step increment ## `page_increment` -the page increment. +the page increment ## `page_size` -the page size. +the page size # Returns -a new `Adjustment`. - +a new `Adjustment` + Emits a `Adjustment::changed` signal from the `Adjustment`. This is typically called by the owner of the `Adjustment` after it has changed any of the `Adjustment` properties other than the value. - + +# Deprecated since 3.18 + +GTK+ emits `Adjustment::changed` itself whenever any + of the properties (other than value) change + Updates the `Adjustment:value` property to ensure that the range between `lower` and `upper` is in the current page (i.e. between -`Adjustment:value` and `Adjustment:value` + `Adjustment:page_size`). +`Adjustment:value` and `Adjustment:value` + `Adjustment:page-size`). If the range is larger than the page size, then only the start of it will be in the current page. -A `Adjustment::changed` signal will be emitted if the value is changed. + +A `Adjustment::value-changed` signal will be emitted if the value is changed. ## `lower` -the lower value. +the lower value ## `upper` -the upper value. - +the upper value + Sets all properties of the adjustment at once. -Use this function to avoid multiple emissions of the `Adjustment::changed` -signal. See `Adjustment::set_lower` for an alternative way -of compressing multiple emissions of `Adjustment::changed` into one. +Use this function to avoid multiple emissions of the +`Adjustment::changed` signal. See `AdjustmentExt::set_lower` +for an alternative way of compressing multiple emissions of +`Adjustment::changed` into one. ## `value` the new value ## `lower` @@ -652,114 +683,118 @@ the new step increment the new page increment ## `page_size` the new page size - + Retrieves the minimum value of the adjustment. # Returns -The current minimum value of the adjustment. - +The current minimum value of the adjustment + Gets the smaller of step increment and page increment. # Returns the minimum increment of `self` - + Retrieves the page increment of the adjustment. # Returns -The current page increment of the adjustment. - +The current page increment of the adjustment + Retrieves the page size of the adjustment. # Returns -The current page size of the adjustment. - +The current page size of the adjustment + Retrieves the step increment of the adjustment. # Returns The current step increment of the adjustment. - + Retrieves the maximum value of the adjustment. # Returns -The current maximum value of the adjustment. - -Gets the current value of the adjustment. See -gtk_adjustment_set_value (). +The current maximum value of the adjustment + +Gets the current value of the adjustment. +See `AdjustmentExt::set_value`. # Returns -The current value of the adjustment. - +The current value of the adjustment + Sets the minimum value of the adjustment. When setting multiple adjustment properties via their individual -setters, multiple `Adjustment::changed` signals will be emitted. However, since -the emission of the `Adjustment::changed` signal is tied to the emission of the -`gobject::Object::notify` signals of the changed properties, it’s possible -to compress the `Adjustment::changed` signals into one by calling -`gobject::Object::freeze_notify` and `gobject::Object::thaw_notify` around the -calls to the individual setters. - -Alternatively, using a single `gobject::Object::set` for all the properties -to change, or using `Adjustment::configure` has the same effect +setters, multiple `Adjustment::changed` signals will be emitted. +However, since the emission of the `Adjustment::changed` signal +is tied to the emission of the `gobject::Object::notify` signals of the changed +properties, it’s possible to compress the `Adjustment::changed` +signals into one by calling `gobject::ObjectExt::freeze_notify` and +`gobject::ObjectExt::thaw_notify` around the calls to the individual setters. + +Alternatively, using a single `gobject::ObjectExt::set` for all the properties +to change, or using `AdjustmentExt::configure` has the same effect of compressing `Adjustment::changed` emissions. ## `lower` the new minimum value - + Sets the page increment of the adjustment. -See `Adjustment::set_lower` about how to compress multiple -emissions of the `Adjustment::changed` signal when setting multiple adjustment -properties. +See `AdjustmentExt::set_lower` about how to compress multiple +emissions of the `Adjustment::changed` signal when setting +multiple adjustment properties. ## `page_increment` the new page increment - + Sets the page size of the adjustment. -See `Adjustment::set_lower` about how to compress multiple -emissions of the `Adjustment`::changed signal when setting multiple adjustment -properties. +See `AdjustmentExt::set_lower` about how to compress multiple +emissions of the `Adjustment`::changed signal when setting +multiple adjustment properties. ## `page_size` the new page size - + Sets the step increment of the adjustment. -See `Adjustment::set_lower` about how to compress multiple -emissions of the `Adjustment::changed` signal when setting multiple adjustment -properties. +See `AdjustmentExt::set_lower` about how to compress multiple +emissions of the `Adjustment::changed` signal when setting +multiple adjustment properties. ## `step_increment` 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. +Note that values will be restricted by `upper - page-size` +if the page-size property is nonzero. -See `Adjustment::set_lower` about how to compress multiple -emissions of the `Adjustment::changed` signal when setting multiple adjustment -properties. +See `AdjustmentExt::set_lower` about how to compress multiple +emissions of the `Adjustment::changed` signal when setting +multiple adjustment properties. ## `upper` the new maximum value - + Sets the `Adjustment` value. The value is clamped to lie between `Adjustment:lower` and `Adjustment:upper`. -Note that for adjustments which are used in a `Scrollbar`, the effective -range of allowed values goes from `Adjustment:lower` to -`Adjustment:upper` - `Adjustment:page_size`. +Note that for adjustments which are used in a `Scrollbar`, the +effective range of allowed values goes from `Adjustment:lower` to +`Adjustment:upper` - `Adjustment:page-size`. ## `value` -the new value. - -Emits a `Adjustment::value_changed` signal from the `Adjustment`. +the new value + +Emits a `Adjustment::value-changed` signal from the `Adjustment`. This is typically called by the owner of the `Adjustment` after it has changed the `Adjustment:value` property. + +# Deprecated since 3.18 + +GTK+ emits `Adjustment::value-changed` itself whenever + the value changes Controls how a widget deals with extra space in a single (x or y) dimension. @@ -812,7 +847,13 @@ child widget. # Implements -[`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`AlignmentExt`](trait.AlignmentExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +`[Deprecated since 3.14]` Trait containing all `Alignment` methods. + +# Implementors + +[`Alignment`](struct.Alignment.html) Creates a new `Alignment`. @@ -838,7 +879,7 @@ the amount that the child widget expands vertically to fill up # Returns the new `Alignment` - + Gets the padding on the different sides of the widget. See gtk_alignment_set_padding (). @@ -857,7 +898,7 @@ location to store the padding ## `padding_right` location to store the padding for the right of the widget, or `None` - + Sets the `Alignment` values. # Deprecated since 3.14 @@ -878,7 +919,7 @@ the amount that the child widget expands horizontally to fill up ## `yscale` 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 @@ -929,7 +970,7 @@ Returns the currently selected application. # Returns a `gio::AppInfo` for the currently selected - application, or `None` if none is selected. Free with `gobject::Object::unref` + application, or `None` if none is selected. Free with `gobject::ObjectExt::unref` Returns the current value of the `AppChooser:content-type` property. @@ -943,15 +984,21 @@ Reloads the list of applications. Note that `AppChooserDialog` does not have any interesting methods of its own. Instead, you should get the embedded `AppChooserWidget` -using `AppChooserDialog::get_widget` and call its methods if +using `AppChooserDialogExt::get_widget` and call its methods if the generic `AppChooser` interface is not sufficient for your needs. To set the heading that is shown above the `AppChooserWidget`, -use `AppChooserDialog::set_heading`. +use `AppChooserDialogExt::set_heading`. # Implements -[`DialogExt`](trait.DialogExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`AppChooserExt`](trait.AppChooserExt.html) +[`AppChooserDialogExt`](trait.AppChooserDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`AppChooserExt`](trait.AppChooserExt.html) + +Trait containing all `AppChooserDialog` methods. + +# Implementors + +[`AppChooserDialog`](struct.AppChooserDialog.html) Creates a new `AppChooserDialog` for the provided `gio::File`, to allow the user to select an application for it. @@ -978,20 +1025,20 @@ a content type string # Returns a newly created `AppChooserDialog` - + Returns the text to display at the top of the dialog. # Returns the text to display at the top of the dialog, or `None`, in which case a default text is displayed - + Returns the `AppChooserWidget` of this dialog. # Returns the `AppChooserWidget` of `self` - + Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. ## `heading` @@ -1015,9 +1062,19 @@ about these groups of applications. To keep track of the selected application, use the `AppChooserWidget::application-selected` and `AppChooserWidget::application-activated` signals. +# CSS nodes + +`AppChooserWidget` has a single CSS node with name appchooser. + # Implements -[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html), [`AppChooserExt`](trait.AppChooserExt.html) +[`AppChooserWidgetExt`](trait.AppChooserWidgetExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html), [`AppChooserExt`](trait.AppChooserExt.html) + +Trait containing all `AppChooserWidget` methods. + +# Implementors + +[`AppChooserWidget`](struct.AppChooserWidget.html) Creates a new `AppChooserWidget` for applications that can handle content of the given type. @@ -1027,74 +1084,74 @@ the content type to show applications for # Returns a newly created `AppChooserWidget` - + Returns the text that is shown if there are not applications that can handle the content type. # Returns the value of `AppChooserWidget:default-text` - + Returns the current value of the `AppChooserWidget:show-all` property. # Returns the value of `AppChooserWidget:show-all` - + Returns the current value of the `AppChooserWidget:show-default` property. # Returns the value of `AppChooserWidget:show-default` - + Returns the current value of the `AppChooserWidget:show-fallback` property. # Returns the value of `AppChooserWidget:show-fallback` - + Returns the current value of the `AppChooserWidget:show-other` property. # Returns the value of `AppChooserWidget:show-other` - + Returns the current value of the `AppChooserWidget:show-recommended` property. # Returns the value of `AppChooserWidget:show-recommended` - + Sets the text that is shown if there are not applications that can handle the content type. ## `text` the new value for `AppChooserWidget:default-text` - + Sets whether the app chooser should show all applications in a flat list. ## `setting` the new value for `AppChooserWidget:show-all` - + Sets whether the app chooser should show the default handler for the content type in a separate section. ## `setting` the new value for `AppChooserWidget:show-default` - + Sets whether the app chooser should show related applications for the content type in a separate section. ## `setting` the new value for `AppChooserWidget:show-fallback` - + Sets whether the app chooser should show applications which are unrelated to the content type. ## `setting` the new value for `AppChooserWidget:show-other` - + Sets whether the app chooser should show recommended applications for the content type in a separate section. ## `setting` @@ -1125,27 +1182,37 @@ associated with `ApplicationWindow` and to the “activate” and ## Automatic resources ## {`automatic`-resources} `Application` will automatically load menus from the `Builder` -file located at "gtk/menus.ui", relative to the application's -resource base path (see `gio::Application::set_resource_base_path`). The +resource located at "gtk/menus.ui", relative to the application's +resource base path (see `gio::ApplicationExt::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 `Application::get_menu_by_id` which allows for +and accessed via `GtkApplicationExt::get_menu_by_id` which allows for dynamic population of a part of the menu structure. -If the files "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are -present then these files will be used in preference, depending on the -value of `Application::prefers_app_menu`. +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 `GtkApplicationExt::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 -`Application::set_app_menu` and `Application::set_menubar`. +`GtkApplicationExt::set_app_menu` and `GtkApplicationExt::set_menubar`. `Application` 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 `IconTheme::add_resource_path` for more +resources. See `IconThemeExt::add_resource_path` for more information. +If there is a resource located at "gtk/help-overlay.ui" which +defines a `ShortcutsWindow` with ID "help_overlay" then `Application` +associates an instance of this shortcuts window with each +`ApplicationWindow` 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) @@ -1156,7 +1223,7 @@ property) and offers various functionality related to the session life-cycle. An application can block various ways to end the session with -the `Application::inhibit` function. Typical use cases for +the `GtkApplicationExt::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 @@ -1169,7 +1236,13 @@ session while inhibitors are present. # Implements -[`ApplicationExt`](trait.ApplicationExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html), [`ActionMapExt`](trait.ActionMapExt.html) +[`ApplicationExt`](trait.ApplicationExt.html), [`ApplicationExt`](trait.ApplicationExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html), [`ActionMapExt`](trait.ActionMapExt.html) + +Trait containing all `Application` methods. + +# Implementors + +[`Application`](struct.Application.html) Creates a new `Application` instance. @@ -1203,7 +1276,7 @@ the application flags # Returns a new `Application` instance - + Installs an accelerator that will cause the named action to be activated when the key combination specificed by `accelerator` is pressed. @@ -1217,13 +1290,13 @@ are referred to with an “app.” prefix, and window-specific actions with a “win.” prefix. `Application` also extracts accelerators out of “accel” attributes -in the `GMenuModels` passed to `Application::set_app_menu` and -`Application::set_menubar`, which is usually more convenient +in the `GMenuModels` passed to `GtkApplicationExt::set_app_menu` and +`GtkApplicationExt::set_menubar`, which is usually more convenient than calling this function for each accelerator. # Deprecated since 3.14 -Use `Application::set_accels_for_action` instead +Use `GtkApplicationExt::set_accels_for_action` instead ## `accelerator` accelerator string ## `action_name` @@ -1231,21 +1304,25 @@ the name of the action to activate ## `parameter` parameter to pass when activating the action, or `None` if the action does not accept an activation parameter - + Adds a window to `self`. +This call can only happen after the `self` has started; +typically, you should add new application windows in response +to the emission of the `gio::Application::activate` signal. + This call is equivalent to setting the `Window:application` property of `window` to `self`. Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly -remove it with `Application::remove_window`. +remove it with `GtkApplicationExt::remove_window`. -GTK+ will keep the application running as long as it has +GTK+ will keep the `self` running as long as it has any windows. ## `window` a `Window` - + Gets the accelerators that are currently associated with the given action. @@ -1259,7 +1336,7 @@ a detailed action name, specifying an action accelerators for `detailed_action_name`, as a `None`-terminated array. Free with `g_strfreev` when no longer needed - + 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. @@ -1284,7 +1361,7 @@ an accelerator that can be parsed by `gtk_accelerator_parse` # Returns a `None`-terminated array of actions for `accel` - + Gets the “active” window for the application. The active window is the one that was most recently focused (within @@ -1298,14 +1375,15 @@ Feature: `v3_6` # Returns the active window - + Returns the menu model that has been set with -`Application::set_app_menu`. +`GtkApplicationExt::set_app_menu`. # Returns the application menu of `self` - + or `None` if no application menu has been set. + Gets a menu from automatically loaded resources. See [Automatic resources][automatic-resources] for more information. @@ -1319,16 +1397,19 @@ the id of the menu to look up Gets the menu with the given id from the automatically loaded resources - + Returns the menu model that has been set with -`Application::set_menubar`. +`GtkApplicationExt::set_menubar`. # Returns the menubar for windows of `self` - + Returns the `ApplicationWindow` with the given ID. +The ID of a `ApplicationWindow` can be retrieved with +`ApplicationWindowExt::get_id`. + Feature: `v3_6` ## `id` @@ -1338,7 +1419,7 @@ an identifier number the window with ID `id`, or `None` if there is no window with this ID - + Gets a list of the ``GtkWindows`` associated with `self`. The list is sorted by most recently focused window, such that the first @@ -1352,7 +1433,7 @@ deletion. # Returns a `glib::List` of `Window` - + 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. @@ -1361,8 +1442,8 @@ 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 `Application::uninhibit` to remove the inhibitor. Note that -an application can have multiple inhibitors, and all of the must +call `GtkApplicationExt::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. @@ -1385,10 +1466,10 @@ a short, human-readable string that explains # Returns A non-zero cookie that is used to uniquely identify this - request. It should be used as an argument to `Application::uninhibit` + request. It should be used as an argument to `GtkApplicationExt::uninhibit` in order to remove the request. If the platform does not support inhibiting or the request failed for some reason, 0 is returned. - + Determines if any of the actions specified in `flags` are currently inhibited (possibly by another application). ## `flags` @@ -1397,9 +1478,9 @@ what types of actions should be queried # Returns `true` if any of the actions specified in `flags` are inhibited - + Lists the detailed action names which have associated accelerators. -See `Application::set_accels_for_action`. +See `GtkApplicationExt::set_accels_for_action`. Feature: `v3_12` @@ -1408,18 +1489,18 @@ Feature: `v3_12` a `None`-terminated array of strings, free with `g_strfreev` when done - + 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 -`Application::set_app_menu` with the contents of an application +`GtkApplicationExt::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 `Application::set_app_menu` even +free to ignore it. If you call `GtkApplicationExt::set_app_menu` even if the desktop environment doesn't support app menus, then a fallback will be provided. @@ -1441,7 +1522,7 @@ 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 -`Application::set_app_menu` anyway, then this menu will be +`GtkApplicationExt::set_app_menu` anyway, then this menu will be replaced with your own. Feature: `v3_14` @@ -1450,19 +1531,19 @@ Feature: `v3_14` # Returns `true` if you should set an app menu - + Removes an accelerator that has been previously added -with `Application::add_accelerator`. +with `GtkApplicationExt::add_accelerator`. # Deprecated since 3.14 -Use `Application::set_accels_for_action` instead +Use `GtkApplicationExt::set_accels_for_action` instead ## `action_name` the name of the action to activate ## `parameter` parameter to pass when activating the action, or `None` if the action does not accept an activation parameter - + Remove a window from `self`. If `window` belongs to `self` then this call is equivalent to @@ -1473,7 +1554,7 @@ The application may stop running as a result of a call to this function. ## `window` a `Window` - + Sets zero or more keyboard accelerators that will trigger the given action. The first item in `accels` will be the primary accelerator, which may be displayed in the UI. @@ -1481,6 +1562,9 @@ 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 `gio::Action::parse_detailed_name` and +`gio::Action::print_detailed_name`. + Feature: `v3_12` ## `detailed_action_name` @@ -1489,7 +1573,7 @@ a detailed action name, specifying an action ## `accels` a list of accelerators in the format understood by `gtk_accelerator_parse` - + Sets or unsets the application menu for `self`. This can only be done in the primary instance of the application, @@ -1509,7 +1593,7 @@ Use the base `gio::ActionMap` interface to add actions, to respond to the user selecting these menu items. ## `app_menu` a `gio::MenuModel`, or `None` - + Sets or unsets the menubar for windows of `self`. This is a menubar in the traditional sense. @@ -1530,17 +1614,17 @@ Use the base `gio::ActionMap` interface to add actions, to respond to the user selecting these menu items. ## `menubar` a `gio::MenuModel`, or `None` - -Removes an inhibitor that has been established with `Application::inhibit`. + +Removes an inhibitor that has been established with `GtkApplicationExt::inhibit`. Inhibitors are also cleared when the application exits. ## `cookie` -a cookie that was returned by `Application::inhibit` +a cookie that was returned by `GtkApplicationExt::inhibit` `ApplicationWindow` is a `Window` subclass that offers some extra functionality for better integration with `Application` features. Notably, it can handle both the application menu as well -as the menubar. See `Application::set_app_menu` and -`Application::set_menubar`. +as the menubar. See `GtkApplicationExt::set_app_menu` and +`GtkApplicationExt::set_menubar`. This class implements the `gio::ActionGroup` and `gio::ActionMap` interfaces, to let you add window-specific actions that will be exported by the @@ -1568,13 +1652,10 @@ will display the application menu, but not the menubar. If the desktop environment does not display the menubar, then `ApplicationWindow` will automatically show a `MenuBar` for it. -(see the `Application` docs for some screenshots of how this -looks on different platforms). This behaviour can be overridden with the `ApplicationWindow:show-menubar` property. If the desktop environment does not display the application -menu, then it will automatically be included in the menubar. It can -also be shown as part of client-side window decorations, e.g. by -using `HeaderBar::set_show_close_button`. +menu, then it will automatically be included in the menubar or in the +windows client-side decorations. ## A `ApplicationWindow` with a menubar @@ -1611,7 +1692,9 @@ The XML format understood by `Builder` for `gio::MenuModel` consists of a toplevel `` element, which contains one or more `` elements. Each `` element contains `` and `` elements with a mandatory name attribute. `` elements have the -same content model as ``. +same content model as ``. Instead of ``, you can use `` or `
` +elements. Attribute values can be translated using gettext, like other `Builder` content. `` elements can be marked for translation with a @@ -1620,9 +1703,37 @@ context and translator comments, using the context and comments attributes. To make use of this, the `Builder` 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 `TextDirection` 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 + # Implements -[`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html), [`ActionMapExt`](trait.ActionMapExt.html) +[`ApplicationWindowExt`](trait.ApplicationWindowExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html), [`ActionMapExt`](trait.ActionMapExt.html) + +Trait containing all `ApplicationWindow` methods. + +# Implementors + +[`ApplicationWindow`](struct.ApplicationWindow.html) Creates a new `ApplicationWindow`. ## `application` @@ -1631,7 +1742,17 @@ a `Application` # Returns a newly created `ApplicationWindow` - + +Gets the `ShortcutsWindow` that has been set up with +a prior call to `ApplicationWindowExt::set_help_overlay`. + +Feature: `v3_20` + + +# Returns + +the help overlay associated with `self`, or `None` + Returns the unique ID of the window. If the window has not yet been added to a `Application`, returns `0`. @@ -1642,14 +1763,25 @@ Feature: `v3_6` the unique ID for `self`, or `0` if the window has not yet been added to a `Application` - + Returns whether the window will display a menubar for the app menu and menubar as needed. # Returns `true` if `self` will display a menubar when needed - + +Associates a shortcuts window with the application window, and +sets up an action with the name win.show-help-overlay to present +it. + +`self` takes resposibility for destroying `help_overlay`. + +Feature: `v3_20` + +## `help_overlay` +a `ShortcutsWindow` + Sets whether the window will display a menubar for the app menu and menubar as needed. ## `show_menubar` @@ -1666,7 +1798,7 @@ from `Misc`, it can be padded and/or aligned, to fill exactly the space the programmer desires. Arrows are created with a call to `Arrow::new`. The direction or -style of an arrow can be changed after creation by using `Arrow::set`. +style of an arrow can be changed after creation by using `ArrowExt::set`. `Arrow` has been deprecated; you can simply use a `Image` with a suitable icon name, such as “pan-down-symbolic“. When replacing @@ -1674,12 +1806,17 @@ suitable icon name, such as “pan-down-symbolic“. When replacing doing automatic flipping between `ArrowType::Left` and `ArrowType::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 instead of “pan-left-symbolic“ and -“pan-right-symbolic“ which don't. +react to the text direction. # Implements -[`MiscExt`](trait.MiscExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`ArrowExt`](trait.ArrowExt.html), [`MiscExt`](trait.MiscExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +`[Deprecated since 3.14]` Trait containing all `Arrow` methods. + +# Implementors + +[`Arrow`](struct.Arrow.html) Creates a new `Arrow` widget. @@ -1694,7 +1831,7 @@ a valid `ShadowType`. # Returns the new `Arrow` widget. - + Sets the direction and style of the `Arrow`, `self`. # Deprecated since 3.14 @@ -1704,14 +1841,6 @@ Use a `Image` with a suitable icon. a valid `ArrowType`. ## `shadow_type` a valid `ShadowType`. - -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. @@ -1733,9 +1862,19 @@ derives from `Frame`, 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 + +`AspectFrame` uses a CSS node with name frame. + # Implements -[`FrameExt`](trait.FrameExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`AspectFrameExt`](trait.AspectFrameExt.html), [`FrameExt`](trait.FrameExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `AspectFrame` methods. + +# Implementors + +[`AspectFrame`](struct.AspectFrame.html) Create a new `AspectFrame`. ## `label` @@ -1757,7 +1896,7 @@ If `true`, `ratio` is ignored, and the aspect # Returns the new `AspectFrame`. - + Set parameters for an existing `AspectFrame`. ## `xalign` Horizontal alignment of the child within the allocation of @@ -1772,6 +1911,301 @@ The desired aspect ratio. ## `obey_child` If `true`, `ratio` is ignored, and the aspect ratio is taken from the requistion of the child. + +A `Assistant` 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 `Assistant` is that it controls what buttons to show +and to make sensitive, based on what it knows about the page sequence +and the [type][`AssistantPageType`] 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 `AssistantPageType::Custom` page +type and handle buttons yourself. + +# `Assistant` as `Buildable` + +The `Assistant` implementation of the `Buildable` interface +exposes the `action_area` as internal children with the name +“action_area”. + +To add pages to an assistant in `Builder`, simply add it as a +child to the `Assistant` object, and set its child properties +as necessary. + +# CSS nodes + +`Assistant` has a single CSS node with the name assistant. + +# Implements + +[`AssistantExt`](trait.AssistantExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Assistant` methods. + +# Implementors + +[`Assistant`](struct.Assistant.html) + +Creates a new `Assistant`. + +# Returns + +a newly created `Assistant` + +Adds a widget to the action area of a `Assistant`. +## `child` +a `Widget` + +Appends a page to the `self`. +## `page` +a `Widget` + +# Returns + +the index (starting at 0) of the inserted page + +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. + +Returns the page number of the current page. + +# Returns + +The index (starting from 0) of the current + page in the `self`, or -1 if the `self` has no pages, + or no current page. + +Returns the number of pages in the `self` + +# Returns + +the number of pages in the `self` + +Returns the child widget contained in page number `page_num`. +## `page_num` +the index of a page in the `self`, + or -1 to get the last page + +# Returns + +the child widget, or `None` + if `page_num` is out of bounds + +Gets whether `page` is complete. +## `page` +a page of `self` + +# Returns + +`true` if `page` is complete. + +Gets whether page has padding. + +Feature: `v3_18` + +## `page` +a page of `self` + +# Returns + +`true` if `page` has padding + +Gets the header image for `page`. + +# Deprecated since 3.2 + +Since GTK+ 3.2, a header is no longer shown; + add your header decoration to the page content instead. +## `page` +a page of `self` + +# Returns + +the header image for `page`, + or `None` if there’s no header image for the page + +Gets the side image for `page`. + +# Deprecated since 3.2 + +Since GTK+ 3.2, sidebar images are not + shown anymore. +## `page` +a page of `self` + +# Returns + +the side image for `page`, + or `None` if there’s no side image for the page + +Gets the title for `page`. +## `page` +a page of `self` + +# Returns + +the title for `page` + +Gets the page type of `page`. +## `page` +a page of `self` + +# Returns + +the page type of `page` + +Inserts a page in the `self` at a given position. +## `page` +a `Widget` +## `position` +the index (starting at 0) at which to insert the page, + or -1 to append the page to the `self` + +# Returns + +the index (starting from 0) of the inserted page + +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 +`AssistantPageType::Custom` type. + +Prepends a page to the `self`. +## `page` +a `Widget` + +# Returns + +the index (starting at 0) of the inserted page + +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 +`AssistantPageType::Custom` type. + +Removes a widget from the action area of a `Assistant`. +## `child` +a `Widget` + +Removes the `page_num`’s page from `self`. +## `page_num` +the index of a page in the `self`, + 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 `self` flow can be set with +`AssistantExt::set_forward_page_func`. +## `page_num` +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 `self`, 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 `None` will make the assistant to +use the default forward function, which just goes to the +next visible page. +## `page_func` +the ``GtkAssistantPageFunc``, or `None` + to use the default one +## `data` +user data for `page_func` +## `destroy` +destroy notifier for `data` + +Sets whether `page` contents are complete. + +This will make `self` update the buttons state +to be able to continue the task. +## `page` +a page of `self` +## `complete` +the completeness status of the page + +Sets whether the assistant is adding padding around +the page. + +Feature: `v3_18` + +## `page` +a page of `self` +## `has_padding` +whether this page has padding + +Sets a header image for `page`. + +# Deprecated since 3.2 + +Since GTK+ 3.2, a header is no longer shown; + add your header decoration to the page content instead. +## `page` +a page of `self` +## `pixbuf` +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. + +# Deprecated since 3.2 + +Since GTK+ 3.2, sidebar images are not + shown anymore. +## `page` +a page of `self` +## `pixbuf` +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. +## `page` +a page of `self` +## `title` +the new title for `page` + +Sets the page type for `page`. + +The page type determines the page behavior in the `self`. +## `page` +a page of `self` +## `type_` +the new type for `page` + +Forces `self` 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. An enum for determining the page role inside the `Assistant`. It's used to handle buttons sensitivity and visibility. @@ -1781,7 +2215,7 @@ Note that an assistant needs to end its page flow with a page of type `AssistantPageType::Progress` to be correct. The Cancel button will only be shown if the page isn’t “committed”. -See `Assistant::commit` for details. +See `AssistantExt::commit` for details. The page has regular contents. Both the Back and forward buttons will be shown. @@ -1802,7 +2236,7 @@ Used for tasks that take a long time to Used for when other page types are not appropriate. No buttons will be shown, and the application must - add its own buttons through `Assistant::add_action_widget`. + add its own buttons through `AssistantExt::add_action_widget`. Whenever a container has some form of natural row it may align children in that row along a common typographical baseline. If @@ -1844,28 +2278,6 @@ added, so you do not need to unref it. # Returns pointer to child of the `Bin` - -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 `BorderStyle::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 `Box` widget organizes child widgets into a rectangular area. @@ -1887,9 +2299,9 @@ Use repeated calls to `BoxExt::pack_start` to pack widgets into a end to start. You may intersperse these calls and add widgets from both ends of the same `Box`. -Because `Box` is a `Container`, you may also use `Container::add` +Because `Box` is a `Container`, you may also use `ContainerExt::add` to insert widgets into the box, and they will be packed with the default -values for expand and fill child properties. Use `Container::remove` +values for expand and fill child properties. Use `ContainerExt::remove` to remove widgets from the `Box`. Use `BoxExt::set_homogeneous` to specify whether or not all children @@ -1911,6 +2323,14 @@ Use `BoxExt::query_child_packing` to query these fields. Note that a single-row or single-column `Grid` provides exactly the same functionality as `Box`. +# CSS nodes + +`Box` 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. + # Implements [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html) @@ -1919,7 +2339,7 @@ Trait containing all `Box` methods. # Implementors -[`AppChooserWidget`](struct.AppChooserWidget.html), [`Box`](struct.Box.html), [`ButtonBox`](struct.ButtonBox.html), [`ColorChooserWidget`](struct.ColorChooserWidget.html), [`FileChooserWidget`](struct.FileChooserWidget.html), [`FontChooserWidget`](struct.FontChooserWidget.html), [`InfoBar`](struct.InfoBar.html), [`RecentChooserWidget`](struct.RecentChooserWidget.html), [`StackSwitcher`](struct.StackSwitcher.html), [`Statusbar`](struct.Statusbar.html) +[`AppChooserWidget`](struct.AppChooserWidget.html), [`Box`](struct.Box.html), [`ButtonBox`](struct.ButtonBox.html), [`ColorChooserWidget`](struct.ColorChooserWidget.html), [`FileChooserButton`](struct.FileChooserButton.html), [`FileChooserWidget`](struct.FileChooserWidget.html), [`FontChooserWidget`](struct.FontChooserWidget.html), [`InfoBar`](struct.InfoBar.html), [`RecentChooserWidget`](struct.RecentChooserWidget.html), [`StackSwitcher`](struct.StackSwitcher.html), [`Statusbar`](struct.Statusbar.html) Creates a new `Box`. ## `orientation` @@ -1948,6 +2368,7 @@ Feature: `v3_12` # Returns the center widget + or `None` in case no center widget is set. Returns whether the box is homogeneous (all children are the same size). See `BoxExt::set_homogeneous`. @@ -2094,27 +2515,27 @@ In the (unusual) case that you want to add user interface descriptions from multiple sources to the same `Builder` you can call `Builder::new` to get an empty builder and populate it by (multiple) calls to `Builder::add_from_file`, -`Builder::add_from_resource` or `Builder::add_from_string`. +`BuilderExt::add_from_resource` or `BuilderExt::add_from_string`. A `Builder` 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 `Widget::destroy` +builder, it is the responsibility of the user to call `WidgetExt::destroy` to get rid of them and all the widgets they contain. -The functions `Builder::get_object` and `Builder::get_objects` +The functions `Builder::get_object` and `BuilderExt::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 `Widget::destroy`. Other widgets will either be part of a +with `WidgetExt::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 `gobject::Object::ref` to keep them +Non-widget objects need to be reffed with `gobject::ObjectExt::ref` to keep them beyond the lifespan of the builder. -The function `Builder::connect_signals` and variants thereof can be +The function `BuilderExt::connect_signals` and variants thereof can be used to connect handlers to the named signals in the description. # `Builder` UI Definitions # {`BUILDER`-UI} @@ -2133,7 +2554,7 @@ It is common to use `.ui` as the filename extension for files containing The toplevel element is ``. 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 `Builder::set_translation_domain` on the builder. +calling `BuilderExt::set_translation_domain` on the builder. Objects are described by `` elements, which can contain `` elements to set properties, `` elements which connect signals to handlers, and `` elements, which describe @@ -2181,17 +2602,18 @@ as `true`, strings like “FALSE”, “f”, “no”, “n”, “0” are int 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`). 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 -`Builder::expose_object`. - -In general, `Builder` 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. +and colors (in a format understood by `gdk::RGBA::parse`). + +GVariants can be specified in the format understood by `glib::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 +`BuilderExt::expose_object`. In general, `Builder` 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 @@ -2199,14 +2621,14 @@ property value using the attributes "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 `gobject::Object::bind_property` +For more information see `gobject::ObjectExt::bind_property` Signal handlers are set up with the `` 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 `gmodule::Module::symbol`, but this can be changed by passing a custom ``GtkBuilderConnectFunc`` to -`Builder::connect_signals_full`. The remaining attributes, “after”, +`BuilderExt::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” @@ -2269,13 +2691,19 @@ See the [`Widget` documentation][composite-templates] for details. # Implements -[`ObjectExt`](trait.ObjectExt.html) +[`BuilderExt`](trait.BuilderExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Builder` methods. + +# Implementors + +[`Builder`](struct.Builder.html) Creates a new empty builder object. This function is only useful if you intend to make multiple calls -to `Builder::add_from_file`, `Builder::add_from_resource` -or `Builder::add_from_string` in order to merge multiple UI +to `Builder::add_from_file`, `BuilderExt::add_from_resource` +or `BuilderExt::add_from_string` in order to merge multiple UI descriptions into a single builder. Most users will probably want to use `Builder::new_from_file`, @@ -2336,10 +2764,10 @@ the length of `string`, or -1 # Returns a `Builder` containing the interface described by `string` - + Adds the `callback_symbol` to the scope of `self` under the given `callback_name`. -Using this function overrides the behavior of `Builder::connect_signals` +Using this function overrides the behavior of `BuilderExt::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. @@ -2350,9 +2778,9 @@ Feature: `v3_10` The name of the callback, as expected in the XML ## `callback_symbol` The callback pointer - + A convenience function to add many callbacks instead of calling -`Builder::add_callback_symbol` for each symbol. +`BuilderExt::add_callback_symbol` for each symbol. Feature: `v3_10` @@ -2360,7 +2788,7 @@ Feature: `v3_10` The name of the callback, as expected in the XML ## `first_callback_symbol` The callback pointer - + Parses a file containing a [`Builder` UI definition][BUILDER-UI] and merges it with the current contents of `self`. @@ -2382,7 +2810,7 @@ the name of the file to parse # Returns A positive value on success, 0 if an error occurred - + Parses a resource file containing a [`Builder` UI definition][BUILDER-UI] and merges it with the current contents of `self`. @@ -2401,7 +2829,7 @@ the path of the resource file to parse # Returns A positive value on success, 0 if an error occurred - + Parses a string containing a [`Builder` UI definition][BUILDER-UI] and merges it with the current contents of `self`. @@ -2422,7 +2850,7 @@ the length of `buffer` (may be -1 if `buffer` is nul-terminated) # Returns A positive value on success, 0 if an error occurred - + Parses a file containing a [`Builder` UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of `self`. @@ -2442,7 +2870,7 @@ nul-terminated array of objects to build # Returns A positive value on success, 0 if an error occurred - + Parses a resource file containing a [`Builder` UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of `self`. @@ -2462,7 +2890,7 @@ nul-terminated array of objects to build # Returns A positive value on success, 0 if an error occurred - + Parses a string containing a [`Builder` UI definition][BUILDER-UI] building only the requested objects and merges them with the current contents of `self`. @@ -2483,17 +2911,17 @@ nul-terminated array of objects to build # Returns A positive value on success, 0 if an error occurred - -This method is a simpler variation of `Builder::connect_signals_full`. + +This method is a simpler variation of `BuilderExt::connect_signals_full`. It uses symbols explicitly added to `self` with prior calls to -`Builder::add_callback_symbol`. In the case that symbols are not +`BuilderExt::add_callback_symbol`. In the case that symbols are not explicitly added; it uses `gmodule::Module`’s introspective features (by opening the module `None`) 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 `Builder::add_callback_symbol` is called for +Note that unless `BuilderExt::add_callback_symbol` is called for all signal callbacks which are referenced by the loaded XML, this function will require that `gmodule::Module` be supported on the platform. @@ -2507,15 +2935,15 @@ be compiled with the -Wl,--export-dynamic CFLAGS, and linked against gmodule-export-2.0. ## `user_data` user data to pass back with all signals - + This function can be thought of the interpreted language binding -version of `Builder::connect_signals`, except that it does not +version of `BuilderExt::connect_signals`, except that it does not require GModule to function correctly. ## `func` the function used to connect the signals ## `user_data` arbitrary data that will be passed to the connection function - + Add `object` to the `self` object pool so it can be referenced just like any other object built by builder. @@ -2525,7 +2953,25 @@ Feature: `v3_8` the name of the object exposed to the builder ## `object` 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. +## `widget` +the widget that is being extended +## `template_type` +the type that the template is for +## `buffer` +the string to parse +## `length` +the length of `buffer` (may be -1 if `buffer` is nul-terminated) + +# Returns + +A positive value on success, 0 if an error occurred + Gets the `Application` associated with the builder. The `Application` is used for creating action proxies as requested @@ -2533,7 +2979,7 @@ from XML that the builder is loading. By default, the builder uses the default application: the one from `gio::Application::get_default`. If you want to use another application -for constructing proxies, use `Builder::set_application`. +for constructing proxies, use `BuilderExt::set_application`. Feature: `v3_10` @@ -2542,7 +2988,7 @@ Feature: `v3_10` the application being used by the builder, or `None` - + Gets the object named `name`. Note that this function does not increment the reference count of the returned object. ## `name` @@ -2552,7 +2998,7 @@ name of object to get the object named `name` or `None` if it could not be found in the object tree. - + Gets all objects that have been constructed by `self`. Note that this function does not increment the reference counts of the returned objects. @@ -2562,14 +3008,14 @@ objects. a newly-allocated `glib::SList` containing all the objects constructed by the `Builder` instance. It should be freed by `glib::SList::free` - + Gets the translation domain of `self`. # Returns the translation domain. This string is owned by the builder object and must not be modified or freed. - + Looks up a type by name, using the virtual function that `Builder` has for that purpose. This is mainly used when implementing the `Buildable` interface on a type. @@ -2580,13 +3026,13 @@ type name to lookup the `glib::Type` found for `type_name` or `G_TYPE_INVALID` if no type was found - + Fetches a symbol previously added to `self` -with `Builder::add_callback_symbols` +with `BuilderExt::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 `Builder::connect_signals_full` +using `BuilderExt::connect_signals_full` Feature: `v3_10` @@ -2596,7 +3042,7 @@ The name of the callback # Returns The callback symbol in `self` for `callback_name`, or `None` - + Sets the application associated with `self`. You only need this function if there is more than one `gio::Application` @@ -2606,12 +3052,12 @@ Feature: `v3_10` ## `application` a `Application` - + Sets the translation domain of `self`. See `Builder:translation-domain`. ## `domain` the translation domain or `None` - + This function demarshals a value from a string. This function calls `gobject::Value::init` on the `value` argument, so it need not be initialised beforehand. @@ -2633,8 +3079,8 @@ the `gobject::Value` to store the result in # Returns `true` on success - -Like `Builder::value_from_string`, this function demarshals + +Like `BuilderExt::value_from_string`, this function demarshals a value from a string, but takes a `glib::Type` instead of `gobject::ParamSpec`. This function calls `gobject::Value::init` on the `value` argument, so it need not be initialised beforehand. @@ -2689,6 +3135,8 @@ 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 `Button` 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 @@ -2698,6 +3146,21 @@ The `Button` widget can hold any valid child widget. That is, it can hold almost any other standard `Widget`. The most commonly used child is the `Label`. +# CSS nodes + +`Button` 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 `Button` include +.suggested-action and .destructive-action. In special cases, buttons +can be made round by adding the .circular style class. + +Button-like widgets like `ToggleButton`, `MenuButton`, `VolumeButton`, +`LockButton`, `ColorButton`, `FontButton` or `FileChooserButton` use +style classes such as .toggle, .popup, .scale, .lock, .color, .font, .file +to differentiate themselves from a plain `Button`. + # Implements [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionableExt`](trait.ActionableExt.html) @@ -2706,10 +3169,10 @@ Trait containing all `Button` methods. # Implementors -[`Button`](struct.Button.html), [`ColorButton`](struct.ColorButton.html), [`FontButton`](struct.FontButton.html), [`LinkButton`](struct.LinkButton.html), [`ScaleButton`](struct.ScaleButton.html), [`ToggleButton`](struct.ToggleButton.html) +[`Button`](struct.Button.html), [`ColorButton`](struct.ColorButton.html), [`FontButton`](struct.FontButton.html), [`LinkButton`](struct.LinkButton.html), [`ModelButton`](struct.ModelButton.html), [`ScaleButton`](struct.ScaleButton.html), [`ToggleButton`](struct.ToggleButton.html) Creates a new `Button` widget. To add a child widget to the button, -use `Container::add`. +use `ContainerExt::add`. # Returns @@ -2729,7 +3192,7 @@ Feature: `v3_10` ## `icon_name` an icon name ## `size` -an icon size +an icon size (`IconSize`) # Returns @@ -2814,6 +3277,10 @@ This function should be rarely needed. Returns whether the button grabs focus when it is clicked with the mouse. See `ButtonExt::set_focus_on_click`. +# Deprecated since 3.20 + +Use `WidgetExt::get_focus_on_click` instead + # Returns `true` if the button grabs focus when it is clicked with @@ -2825,7 +3292,8 @@ or constructed by `Button::new_from_stock`. # Returns -a `Widget` or `None` in case there is no image +a `Widget` or `None` in case + there is no image Gets the position of the image relative to the text inside the button. @@ -2917,13 +3385,17 @@ 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. + +# Deprecated since 3.20 + +Use `WidgetExt::set_focus_on_click` instead ## `focus_on_click` whether the button grabs focus when clicked with the mouse Set the image of `self` to the given widget. The image will be displayed if the label text is `None` or if `Button:always-show-image` is `true`. You don’t have to call -`Widget::show` on `image` yourself. +`WidgetExt::show` on `image` yourself. ## `image` a widget to set as the image for the button @@ -2965,7 +3437,13 @@ the next character should be used for the mnemonic accelerator key. # Implements -[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html) +[`ButtonBoxExt`](trait.ButtonBoxExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html) + +Trait containing all `ButtonBox` methods. + +# Implementors + +[`ButtonBox`](struct.ButtonBox.html) Creates a new `ButtonBox`. ## `orientation` @@ -2974,7 +3452,7 @@ the box's orientation. # Returns a new `ButtonBox`. - + Returns whether the child is exempted from homogenous sizing. ## `child` @@ -2983,7 +3461,7 @@ a child of `self` # Returns `true` if the child is not subject to homogenous sizing - + Returns whether `child` should appear in a secondary group of children. ## `child` a child of `self` @@ -2991,19 +3469,19 @@ a child of `self` # Returns whether `child` should appear in a secondary group of children. - + Retrieves the method being used to arrange the buttons in a button box. # Returns the method used to lay out buttons in `self`. - + Sets whether the child is exempted from homogeous sizing. ## `child` a child of `self` ## `non_homogeneous` 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. @@ -3012,7 +3490,7 @@ is `ButtonBoxStyle::Start`, `ButtonBoxStyle::Spread` or `ButtonBoxStyle::Edge`, and before the other children if the style is `ButtonBoxStyle::End`. For horizontal button boxes, the definition of before/after depends on direction of the widget (see -`Widget::set_direction`). If the style is `ButtonBoxStyle::Start` +`WidgetExt::set_direction`). If the style is `ButtonBoxStyle::Start` or `ButtonBoxStyle::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. @@ -3021,7 +3499,7 @@ a child of `self` ## `is_secondary` if `true`, the `child` appears in a secondary group of the button box. - + Changes the way buttons are arranged in their container. ## `layout_style` the new layout style @@ -3041,7 +3519,10 @@ Buttons are grouped towards the end of the box, Buttons are centered in the box. Since 2.12. -Buttons expand to fill the box. Since 3.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 `BoxExt::set_homogeneous` and + `BoxExt::set_spacing` manually). Since 3.12. The role specifies the desired appearance of a `ModelButton`. @@ -3053,7 +3534,7 @@ A radio button Prebuilt sets of buttons for the dialog. If none of these choices are appropriate, simply use `ButtonsType::None` -then call `Dialog::add_buttons`. +then call `DialogExt::add_buttons`. > Please note that `ButtonsType::Ok`, `ButtonsType::YesNo` > and `ButtonsType::OkCancel` are discouraged by the @@ -3075,18 +3556,18 @@ OK and Cancel buttons at a time. It can be created with `Calendar::new`. The month and year currently displayed can be altered with -`Calendar::select_month`. The exact day can be selected from the -displayed month using `Calendar::select_day`. +`CalendarExt::select_month`. The exact day can be selected from the +displayed month using `CalendarExt::select_day`. -To place a visual marker on a particular day, use `Calendar::mark_day` -and to remove the marker, `Calendar::unmark_day`. Alternative, all -marks can be cleared with `Calendar::clear_marks`. +To place a visual marker on a particular day, use `CalendarExt::mark_day` +and to remove the marker, `CalendarExt::unmark_day`. Alternative, all +marks can be cleared with `CalendarExt::clear_marks`. The way in which the calendar itself is displayed can be altered using -`Calendar::set_display_options`. +`CalendarExt::set_display_options`. The selected date can be retrieved from a `Calendar` using -`Calendar::get_date`. +`CalendarExt::get_date`. Users should be aware that, although the Gregorian calendar is the legal calendar in most countries, it was adopted progressively @@ -3095,16 +3576,22 @@ historically incorrect. # Implements -[`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`CalendarExt`](trait.CalendarExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Calendar` methods. + +# Implementors + +[`Calendar`](struct.Calendar.html) Creates a new calendar, with the current date being selected. # Returns a newly `Calendar` widget - + Remove all visual markers. - + Obtains the selected date from a `Calendar`. ## `year` location to store the year as a decimal @@ -3115,7 +3602,7 @@ location to store the month number ## `day` location to store the day number (between 1 and 31), or `None` - + Returns if the `day` of the `self` is already marked. ## `day` the day number between 1 and 31. @@ -3123,42 +3610,42 @@ the day number between 1 and 31. # Returns whether the day is marked. - + Queries the height of detail cells, in rows. See `Calendar:detail-width-chars`. # Returns The height of detail cells, in rows. - + Queries the width of detail cells, in characters. See `Calendar:detail-width-chars`. # Returns The width of detail cells, in characters. - + Returns the current display options of `self`. # Returns the display options. - + Places a visual marker on a particular day. ## `day` the day number to mark between 1 and 31. - + Selects a day from the current month. ## `day` the day number between 1 and 31, or 0 to unselect the currently selected day. - + Shifts the calendar to a different month. ## `month` a month number between 0 and 11. ## `year` 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 `Calendar:show-details` is set. @@ -3175,22 +3662,22 @@ a function providing details for each day. data to pass to `func` invokations. ## `destroy` a function for releasing `data`. - + Updates the height of detail cells. See `Calendar:detail-height-rows`. ## `rows` detail height in rows. - + Updates the width of detail cells. See `Calendar:detail-width-chars`. ## `chars` detail width in characters. - + Sets display options (whether to display the heading and the month headings). ## `flags` the display options to set - + Removes the visual marker from a particular day. ## `day` the day number to unmark between 1 and 31. @@ -3850,7 +4337,7 @@ Retrieves a cell area’s initial minimum and natural height. `self` 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 `CellAreaContext::get_preferred_height` after a series of +consult `CellAreaContextExt::get_preferred_height` after a series of requests. ## `context` the `CellAreaContext` to perform this request with @@ -3874,7 +4361,7 @@ fully requested row. If at some point, the width of a single row changes, it should be requested with `CellAreaExt::get_preferred_width` again and then the full width of the requested rows checked again with -`CellAreaContext::get_preferred_width`. +`CellAreaContextExt::get_preferred_width`. ## `context` the `CellAreaContext` which has already been requested for widths. ## `widget` @@ -3891,7 +4378,7 @@ Retrieves a cell area’s initial minimum and natural width. `self` 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 `CellAreaContext::get_preferred_width` after a series of +consult `CellAreaContextExt::get_preferred_width` after a series of requests. ## `context` the `CellAreaContext` to perform this request with @@ -3915,7 +4402,7 @@ fully requested row. If at some point, the height of a single row changes, it should be requested with `CellAreaExt::get_preferred_height` again and then the full height of the requested rows checked again with -`CellAreaContext::get_preferred_height`. +`CellAreaContextExt::get_preferred_height`. ## `context` the `CellAreaContext` which has already been requested for widths. ## `widget` @@ -4023,7 +4510,7 @@ Explicitly sets the currently focused cell to `renderer`. This is generally called by implementations of `CellAreaClass.focus`() or `CellAreaClass.event`(), however it can also be used to implement functions such -as `TreeView::set_cursor_on_cell`. +as `TreeViewExt::set_cursor_on_cell`. ## `renderer` the `CellRenderer` to give focus to @@ -4054,24 +4541,30 @@ side. Alignments of ``GtkCellRenderers`` rendered in adjacent rows can be configured by configuring the `CellAreaBox` align child cell property with `CellArea::cell_set_property` or by specifying the "align" -argument to `CellAreaBox::pack_start` and `CellAreaBox::pack_end`. +argument to `CellAreaBoxExt::pack_start` and `CellAreaBoxExt::pack_end`. # Implements -[`CellAreaExt`](trait.CellAreaExt.html), [`ObjectExt`](trait.ObjectExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`OrientableExt`](trait.OrientableExt.html) +[`CellAreaBoxExt`](trait.CellAreaBoxExt.html), [`CellAreaExt`](trait.CellAreaExt.html), [`ObjectExt`](trait.ObjectExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html), [`OrientableExt`](trait.OrientableExt.html) + +Trait containing all `CellAreaBox` methods. + +# Implementors + +[`CellAreaBox`](struct.CellAreaBox.html) Creates a new `CellAreaBox`. # Returns a newly created `CellAreaBox` - + Gets the spacing added between cell renderers. # Returns the space added between cell renderers in `self`. - + Adds `renderer` to `self`, packed with reference to the end of `self`. The `renderer` is packed after (away from end of) any other @@ -4085,7 +4578,7 @@ more than its natural size whether `renderer` should be aligned in adjacent rows ## `fixed` whether `renderer` should have the same size in all rows - + Adds `renderer` to `self`, packed with reference to the start of `self`. The `renderer` is packed after any other `CellRenderer` packed @@ -4099,7 +4592,7 @@ more than its natural size whether `renderer` should be aligned in adjacent rows ## `fixed` whether `renderer` should have the same size in all rows - + Sets the spacing to add between cell renderers in `self`. ## `spacing` the space to add between ``GtkCellRenderers`` @@ -4117,8 +4610,14 @@ such as `CellAreaExt::render` and `CellAreaExt::event`. # Implements -[`ObjectExt`](trait.ObjectExt.html) - +[`CellAreaContextExt`](trait.CellAreaContextExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `CellAreaContext` methods. + +# Implementors + +[`CellAreaContext`](struct.CellAreaContext.html) + Allocates a width and/or a height for all rows which are to be rendered with `self`. @@ -4137,17 +4636,17 @@ the allocated width for all `TreeModel` rows rendered ## `height` the allocated height for all `TreeModel` rows rendered with `self`, or -1. - + Fetches the current allocation size for `self`. If the context was not allocated in width or height, or if the -context was recently reset with `CellAreaContext::reset`, +context was recently reset with `CellAreaContextExt::reset`, the returned value will be -1. ## `width` location to store the allocated width, or `None` ## `height` location to store the allocated height, or `None` - + Fetches the `CellArea` this `self` was created by. This is generally unneeded by layouting widgets; however, @@ -4162,11 +4661,11 @@ compute a proper allocation. # Returns the `CellArea` this context was created by. - + Gets the accumulative preferred height for all rows which have been requested with this context. -After `CellAreaContext::reset` is called and/or before ever +After `CellAreaContextExt::reset` is called and/or before ever requesting the size of a `CellArea`, the returned values are 0. ## `minimum_height` location to store the minimum height, @@ -4174,11 +4673,11 @@ location to store the minimum height, ## `natural_height` location to store the natural height, or `None` - + Gets the accumulative preferred height for `width` for all rows which have been requested for the same said `width` with this context. -After `CellAreaContext::reset` is called and/or before ever +After `CellAreaContextExt::reset` is called and/or before ever requesting the size of a `CellArea`, the returned values are -1. ## `width` a proposed width for allocation @@ -4188,11 +4687,11 @@ location to store the minimum height, ## `natural_height` location to store the natural height, or `None` - + Gets the accumulative preferred width for all rows which have been requested with this context. -After `CellAreaContext::reset` is called and/or before ever +After `CellAreaContextExt::reset` is called and/or before ever requesting the size of a `CellArea`, the returned values are 0. ## `minimum_width` location to store the minimum width, @@ -4200,11 +4699,11 @@ location to store the minimum width, ## `natural_width` location to store the natural width, or `None` - + Gets the accumulative preferred width for `height` for all rows which have been requested for the same said `height` with this context. -After `CellAreaContext::reset` is called and/or before ever +After `CellAreaContextExt::reset` is called and/or before ever requesting the size of a `CellArea`, the returned values are -1. ## `height` a proposed height for allocation @@ -4214,7 +4713,7 @@ location to store the minimum width, ## `natural_width` location to store the natural width, or `None` - + Causes the minimum and/or natural height to grow if the new proposed sizes exceed the current minimum and natural height. @@ -4226,7 +4725,7 @@ progressively push the requested height over a series of the proposed new minimum height for `self` ## `natural_height` the proposed new natural height for `self` - + Causes the minimum and/or natural width to grow if the new proposed sizes exceed the current minimum and natural width. @@ -4238,7 +4737,7 @@ progressively push the requested width over a series of the proposed new minimum width for `self` ## `natural_width` the proposed new natural width for `self` - + Resets any previously cached request and allocation data. @@ -4391,7 +4890,8 @@ is used by `self`. # Returns -the cell area used by `self`. +the cell area used by `self`, +or `None` in case no cell area is used. Returns the cell renderers which have been added to `self`. @@ -4741,7 +5241,13 @@ The `CellRendererAccel` cell renderer was added in GTK+ 2.10. # Implements -[`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`CellRendererAccelExt`](trait.CellRendererAccelExt.html), [`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `CellRendererAccel` methods. + +# Implementors + +[`CellRendererAccel`](struct.CellRendererAccel.html) Creates a new `CellRendererAccel`. @@ -4774,11 +5280,17 @@ The `CellRendererCombo` cell renderer was added in GTK+ 2.6. # Implements -[`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`CellRendererComboExt`](trait.CellRendererComboExt.html), [`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `CellRendererCombo` methods. + +# Implementors + +[`CellRendererCombo`](struct.CellRendererCombo.html) Creates a new `CellRendererCombo`. Adjust how text is drawn using object properties. -Object properties can be set globally (with `gobject::Object::set`). +Object properties can be set globally (with `gobject::ObjectExt::set`). Also, with `TreeViewColumn`, you can bind a property to a value in a `TreeModel`. For example, you can bind the “text” property on the cell renderer to a string value in the model, thus rendering @@ -4814,11 +5326,17 @@ pixbuf, it renders that one. # Implements -[`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`CellRendererPixbufExt`](trait.CellRendererPixbufExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `CellRendererPixbuf` methods. + +# Implementors + +[`CellRendererPixbuf`](struct.CellRendererPixbuf.html) Creates a new `CellRendererPixbuf`. Adjust rendering parameters using object properties. Object properties can be set -globally (with `gobject::Object::set`). Also, with `TreeViewColumn`, you +globally (with `gobject::ObjectExt::set`). Also, with `TreeViewColumn`, you can bind a property to a value in a `TreeModel`. 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 @@ -4835,7 +5353,13 @@ The `CellRendererProgress` cell renderer was added in GTK+ 2.6. # Implements -[`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html) +[`CellRendererProgressExt`](trait.CellRendererProgressExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html) + +Trait containing all `CellRendererProgress` methods. + +# Implementors + +[`CellRendererProgress`](struct.CellRendererProgress.html) Creates a new `CellRendererProgress`. @@ -4859,7 +5383,13 @@ The `CellRendererSpin` cell renderer was added in GTK+ 2.10. # Implements -[`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`CellRendererSpinExt`](trait.CellRendererSpinExt.html), [`CellRendererTextExt`](trait.CellRendererTextExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `CellRendererSpin` methods. + +# Implementors + +[`CellRendererSpin`](struct.CellRendererSpin.html) Creates a new `CellRendererSpin`. @@ -4880,7 +5410,13 @@ for each cell is to bind them to columns in your tree model using e.g. # Implements -[`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`CellRendererSpinnerExt`](trait.CellRendererSpinnerExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `CellRendererSpinner` methods. + +# Implementors + +[`CellRendererSpinner`](struct.CellRendererSpinner.html) Returns a new cell renderer which will show a spinner to indicate activity. @@ -4908,7 +5444,7 @@ Trait containing all `CellRendererText` methods. Creates a new `CellRendererText`. Adjust how text is drawn using object properties. Object properties can be -set globally (with `gobject::Object::set`). Also, with `TreeViewColumn`, +set globally (with `gobject::ObjectExt::set`). Also, with `TreeViewColumn`, you can bind a property to a value in a `TreeModel`. 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 @@ -4935,11 +5471,17 @@ When activated, it emits the `CellRendererToggle::toggled` signal. # Implements -[`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) +[`CellRendererToggleExt`](trait.CellRendererToggleExt.html), [`CellRendererExt`](trait.CellRendererExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `CellRendererToggle` methods. + +# Implementors + +[`CellRendererToggle`](struct.CellRendererToggle.html) Creates a new `CellRendererToggle`. Adjust rendering parameters using object properties. Object properties can be set -globally (with `gobject::Object::set`). Also, with `TreeViewColumn`, you +globally (with `gobject::ObjectExt::set`). Also, with `TreeViewColumn`, you can bind a property to a value in a `TreeModel`. 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 @@ -4948,35 +5490,35 @@ the model. # Returns the new cell renderer - + Returns whether the cell renderer is activatable. See -`CellRendererToggle::set_activatable`. +`CellRendererToggleExt::set_activatable`. # Returns `true` if the cell renderer is activatable. - + Returns whether the cell renderer is active. See -`CellRendererToggle::set_active`. +`CellRendererToggleExt::set_active`. # Returns `true` if the cell renderer is active. - + Returns whether we’re rendering radio toggles rather than checkboxes. # Returns `true` if we’re rendering radio toggles rather than checkboxes - + Makes the cell renderer activatable. ## `setting` the value to set. - + Activates or deactivates a cell renderer. ## `setting` 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). @@ -4994,15 +5536,32 @@ more information about toggle/check buttons. The important signal ( `ToggleButton::toggled` ) is also inherited from `ToggleButton`. -# Implements +# CSS nodes -[`CheckButtonExt`](trait.CheckButtonExt.html), [`ToggleButtonExt`](trait.ToggleButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionableExt`](trait.ActionableExt.html) - -Trait containing all `CheckButton` methods. -# Implementors +```plain +checkbutton +├── check +╰── +``` -[`CheckButton`](struct.CheckButton.html), [`RadioButton`](struct.RadioButton.html) +A `CheckButton` with indicator (see `ToggleButtonExt::set_mode`) has a +main CSS node with name checkbutton and a subnode with name check. + + +```plain +button.check +├── check +╰── +``` + +A `CheckButton` 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. + +# Implements + +[`ToggleButtonExt`](trait.ToggleButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionableExt`](trait.ActionableExt.html) Creates a new `CheckButton`. @@ -5037,9 +5596,27 @@ A check box indicating the state of the boolean value is displayed at the left side of the `MenuItem`. Activating the `MenuItem` toggles the value. +# CSS nodes + + +```plain +menuitem +├── check.left +╰── +``` + +`CheckMenuItem` has a main CSS node with name menuitem, and a subnode +with name check, which gets the .left or .right style class. + # Implements -[`MenuItemExt`](trait.MenuItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionableExt`](trait.ActionableExt.html) +[`CheckMenuItemExt`](trait.CheckMenuItemExt.html), [`MenuItemExt`](trait.MenuItemExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionableExt`](trait.ActionableExt.html) + +Trait containing all `CheckMenuItem` methods. + +# Implementors + +[`CheckMenuItem`](struct.CheckMenuItem.html), [`RadioMenuItem`](struct.RadioMenuItem.html) Creates a new `CheckMenuItem`. @@ -5065,45 +5642,45 @@ The text of the button, with an underscore in front of the # Returns a new `CheckMenuItem` - + Returns whether the check menu item is active. See gtk_check_menu_item_set_active (). # Returns `true` if the menu item is checked. - + Returns whether `self` looks like a `RadioMenuItem` # Returns Whether `self` looks like a `RadioMenuItem` - -Retrieves the value set by `CheckMenuItem::set_inconsistent`. + +Retrieves the value set by `CheckMenuItemExt::set_inconsistent`. # Returns `true` if inconsistent - + Sets the active state of the menu item’s check box. ## `is_active` boolean value indicating whether the check box is active. - + Sets whether `self` is drawn like a `RadioMenuItem` ## `draw_as_radio` whether `self` is drawn like a `RadioMenuItem` - + 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, `CheckMenuItem::set_inconsistent` only affects +done manually, `CheckMenuItemExt::set_inconsistent` only affects visual appearance, it doesn’t affect the semantics of the widget. ## `setting` `true` to display an “inconsistent” third state check - + Emits the `CheckMenuItem::toggled` signal. The `Clipboard` object represents a clipboard of data shared @@ -5119,13 +5696,13 @@ 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 `Clipboard::set_text`), or you can supply a +functions like `ClipboardExt::set_text`), or you can supply a callback to be called at a later time when the data is needed (via -`Clipboard::set_with_data` or `Clipboard::set_with_owner`.) +`ClipboardExt::set_with_data` or `ClipboardExt::set_with_owner`.) Providing a callback also avoids having to make copies of the data when it is not needed. -`Clipboard::set_with_data` and `Clipboard::set_with_owner` +`ClipboardExt::set_with_data` and `ClipboardExt::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 @@ -5136,7 +5713,7 @@ contents of clipboard reflect the internal state of a `gobject::Object` (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 `Clipboard::set_with_owner` to update +entry widget can call `ClipboardExt::set_with_owner` to update the timestamp for clipboard ownership, without having to worry about `clear_func` being called. @@ -5146,10 +5723,10 @@ 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, `Clipboard::request_contents` takes a +to request the selection, `ClipboardExt::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 `Clipboard::wait_for_contents`. +a separate callback, you can also use `ClipboardExt::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 @@ -5157,8 +5734,8 @@ 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, `Clipboard::request_text` and -`Clipboard::wait_for_text`. These functions take care of +it as text, `ClipboardExt::request_text` and +`ClipboardExt::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 @@ -5166,7 +5743,13 @@ form for representing strings in GTK+.) # Implements -[`ObjectExt`](trait.ObjectExt.html) +[`ClipboardExt`](trait.ClipboardExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Clipboard` methods. + +# Implementors + +[`Clipboard`](struct.Clipboard.html) Returns the clipboard object for the given selection. See `Clipboard::get_for_display` for complete details. @@ -5229,29 +5812,38 @@ 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. - + Clears the contents of the clipboard. Generally this should only -be called between the time you call `Clipboard::set_with_owner` -or `Clipboard::set_with_data`, +be called between the time you call `ClipboardExt::set_with_owner` +or `ClipboardExt::set_with_data`, and when the `clear_func` you supplied is called. Otherwise, the clipboard may be owned by someone else. - + Gets the `gdk::Display` associated with `self` # Returns the `gdk::Display` associated with `self` - + If the clipboard contents callbacks were set with -`Clipboard::set_with_owner`, and the `Clipboard::set_with_data` or -`Clipboard::clear` has not subsequently called, returns the owner set -by `Clipboard::set_with_owner`. +`ClipboardExt::set_with_owner`, and the `ClipboardExt::set_with_data` or +`ClipboardExt::clear` has not subsequently called, returns the owner set +by `ClipboardExt::set_with_owner`. # Returns the owner of the clipboard, if any; otherwise `None`. - + +Gets the selection that this clipboard is for. + +Feature: `v3_22` + + +# Returns + +the selection + Requests the contents of clipboard as the given target. When the results of the result are later received the supplied callback will be called. @@ -5264,7 +5856,7 @@ A function to call when the results are received `selection_data` will be negative. ## `user_data` 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 `gdk_pixbuf::Pixbuf`, and `callback` will be called. @@ -5279,7 +5871,7 @@ 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` 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. @@ -5295,7 +5887,7 @@ 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` 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. @@ -5307,7 +5899,7 @@ a function to call when the targets are one way or the other.) ## `user_data` 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. @@ -5321,7 +5913,7 @@ 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` user data to pass to `callback`. - + Requests the contents of the clipboard as URIs. When the URIs are later received `callback` will be called. @@ -5334,7 +5926,7 @@ 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` 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. @@ -5347,14 +5939,14 @@ array containing to indicate that all forms should be stored. ## `n_targets` number of elements in `targets` - + Sets the contents of the clipboard to the given `gdk_pixbuf::Pixbuf`. GTK+ will take responsibility for responding for requests for the image, and for converting the image into the requested format. ## `pixbuf` a `gdk_pixbuf::Pixbuf` - + 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 @@ -5364,7 +5956,7 @@ a UTF-8 string. ## `len` 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. @@ -5387,12 +5979,12 @@ user data to pass to `get_func` and `clear_func`. `true` if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback functions will be ignored. - + 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 `Clipboard::set_with_data` +The difference between this function and `ClipboardExt::set_with_data` is that instead of an generic `user_data` pointer, a `gobject::Object` is passed in. ## `targets` @@ -5415,10 +6007,10 @@ an object that “owns” the data. This object will be passed `true` if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback functions will be ignored. - + Stores the current clipboard data somewhere so that it will stay around after the application has quit. - + 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. @@ -5432,7 +6024,7 @@ a newly-allocated `SelectionData` object or `None` if retrieving the given target failed. If non-`None`, this value must be freed with `SelectionData::free` when you are finished with it. - + Requests the contents of the clipboard as image and converts the result to a `gdk_pixbuf::Pixbuf`. This function waits for the data to be received using the main loop, so events, @@ -5441,12 +6033,12 @@ timeouts, etc, may be dispatched during the wait. # Returns a newly-allocated `gdk_pixbuf::Pixbuf` - object which must be disposed with `gobject::Object::unref`, or + object which must be disposed with `gobject::ObjectExt::unref`, or `None` 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.) - + 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. @@ -5466,7 +6058,7 @@ a reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into text form.) - + Returns a list of targets that are present on the clipboard, or `None` if there aren’t any targets available. The returned list must be freed with `g_free`. @@ -5483,7 +6075,7 @@ location to store number of items in `targets`. `true` if any targets are present on the clipboard, otherwise `false`. - + 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, @@ -5497,7 +6089,7 @@ a newly-allocated UTF-8 string which must for various reasons, in particular if the clipboard was empty or if the contents of the clipboard could not be converted into text form.) - + 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. @@ -5510,7 +6102,7 @@ timeouts, etc, may be dispatched during the wait. 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.) - + 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 @@ -5518,13 +6110,13 @@ 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 -`Clipboard::wait_for_image` since it doesn’t need to retrieve +`ClipboardExt::wait_for_image` since it doesn’t need to retrieve the actual image data. # Returns `true` is there is an image available, `false` otherwise. - + 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 @@ -5532,7 +6124,7 @@ 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 -`Clipboard::wait_for_rich_text` since it doesn’t need to retrieve +`ClipboardExt::wait_for_rich_text` since it doesn’t need to retrieve the actual text. ## `buffer` a `TextBuffer` @@ -5540,7 +6132,7 @@ a `TextBuffer` # Returns `true` is there is rich text available, `false` otherwise. - + 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. @@ -5553,7 +6145,7 @@ A `gdk::Atom` indicating which target to look for. # Returns `true` if the target is available, `false` otherwise. - + 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 @@ -5561,13 +6153,13 @@ 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 -`Clipboard::wait_for_text` since it doesn’t need to retrieve +`ClipboardExt::wait_for_text` since it doesn’t need to retrieve the actual text. # Returns `true` is there is text available, `false` otherwise. - + 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 @@ -5575,7 +6167,7 @@ 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 -`Clipboard::wait_for_uris` since it doesn’t need to retrieve +`ClipboardExt::wait_for_uris` since it doesn’t need to retrieve the actual URI data. # Returns @@ -5586,9 +6178,20 @@ The `ColorButton` 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 + +`ColorButton` has a single CSS node with name button. To differentiate +it from a plain `Button`, it gets the .color style class. + # Implements -[`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionableExt`](trait.ActionableExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html) +[`ColorButtonExt`](trait.ColorButtonExt.html), [`ButtonExt`](trait.ButtonExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ActionableExt`](trait.ActionableExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html) + +Trait containing all `ColorButton` methods. + +# Implementors + +[`ColorButton`](struct.ColorButton.html) Creates a new color button. @@ -5621,7 +6224,7 @@ A `gdk::RGBA` to set the current color with # Returns a new color button - + Returns the current alpha value. # Deprecated since 3.4 @@ -5631,7 +6234,7 @@ Use `ColorChooser::get_rgba` instead. # Returns an integer between 0 and 65535 - + Sets `color` to be the current color in the `ColorButton` widget. # Deprecated since 3.4 @@ -5639,7 +6242,7 @@ Sets `color` to be the current color in the `ColorButton` widget. Use `ColorChooser::get_rgba` instead. ## `color` a `gdk::Color` to fill in with the current color - + Sets `rgba` to be the current color in the `ColorButton` widget. # Deprecated since 3.4 @@ -5647,13 +6250,13 @@ Sets `rgba` to be the current color in the `ColorButton` widget. Use `ColorChooser::get_rgba` instead. ## `rgba` a `gdk::RGBA` to fill in with the current color - + Gets the title of the color selection dialog. # Returns An internal string, do not free the return value - + Does the color selection dialog use the alpha channel ? # Deprecated since 3.4 @@ -5663,7 +6266,7 @@ Use `ColorChooser::get_use_alpha` instead. # Returns `true` if the color sample uses alpha channel, `false` if not - + Sets the current opacity to be `alpha`. # Deprecated since 3.4 @@ -5671,7 +6274,7 @@ Sets the current opacity to be `alpha`. Use `ColorChooser::set_rgba` instead. ## `alpha` an integer between 0 and 65535 - + Sets the current color to be `color`. # Deprecated @@ -5679,7 +6282,7 @@ Sets the current color to be `color`. Use `ColorChooser::set_rgba` instead. ## `color` A `gdk::Color` to set the current color with - + Sets the current color to be `rgba`. # Deprecated since 3.4 @@ -5687,11 +6290,11 @@ Sets the current color to be `rgba`. Use `ColorChooser::set_rgba` instead. ## `rgba` a `gdk::RGBA` to set the current color with - + Sets the title for the color selection dialog. ## `title` String containing new window title - + Sets whether or not the color button should use the alpha channel. # Deprecated since 3.4 @@ -5768,7 +6371,13 @@ a color. It implements the `ColorChooser` interface. # Implements -[`DialogExt`](trait.DialogExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html) +[`ColorChooserDialogExt`](trait.ColorChooserDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html) + +Trait containing all `ColorChooserDialog` methods. + +# Implementors + +[`ColorChooserDialog`](struct.ColorChooserDialog.html) Creates a new `ColorChooserDialog`. ## `title` @@ -5797,9 +6406,19 @@ To get the selected color use `ColorChooser::get_rgba`. The `ColorChooserWidget` is used in the `ColorChooserDialog` to provide a dialog for selecting colors. +# CSS names + +`ColorChooserWidget` has a single CSS node with name colorchooser. + # Implements -[`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html) +[`ColorChooserWidgetExt`](trait.ColorChooserWidgetExt.html), [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html), [`ColorChooserExt`](trait.ColorChooserExt.html) + +Trait containing all `ColorChooserWidget` methods. + +# Implementors + +[`ColorChooserWidget`](struct.ColorChooserWidget.html) Creates a new `ColorChooserWidget`. @@ -5831,6 +6450,39 @@ can be a bit overwhelming. In this case, `ComboBoxText` offers a simple alternative. Both `ComboBox` and `ComboBoxText` can contain an entry. +# CSS nodes + + +```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. + + +```plain +combobox +├── box.linked +│ ├── entry.combo +│ ╰── button.combo +│ ╰── box +│ ╰── arrow +╰── window.popup +``` + +A `ComboBox` with an entry has a single CSS node with name combobox. It +contains a bx with the .linked class and that box contains an entry and a +button, both with the .combo class added. +The button also contains another node with name arrow. + # Implements [`ComboBoxExt`](trait.ComboBoxExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html) @@ -5959,6 +6611,10 @@ A column in the data source model of `self`. Returns whether the combo box grabs focus when it is clicked with the mouse. See `ComboBoxExt::set_focus_on_click`. +# Deprecated since 3.20 + +Use `WidgetExt::get_focus_on_click` instead + # Returns `true` if the combo box grabs focus when it is @@ -6107,6 +6763,10 @@ 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. + +# Deprecated since 3.20 + +Use `WidgetExt::set_focus_on_click` instead ## `focus_on_click` whether the combo box grabs focus when clicked with the mouse @@ -6167,12 +6827,12 @@ To create a `ComboBoxText`, use `ComboBoxText::new` or `ComboBoxText::new_with_entry`. You can add items to a `ComboBoxText` with -`ComboBoxText::append_text`, `ComboBoxText::insert_text` -or `ComboBoxText::prepend_text` and remove options with -`ComboBoxText::remove`. +`ComboBoxTextExt::append_text`, `ComboBoxTextExt::insert_text` +or `ComboBoxTextExt::prepend_text` and remove options with +`ComboBoxTextExt::remove`. If the `ComboBoxText` contains an entry (via the “has-entry” property), -its contents can be retrieved using `ComboBoxText::get_active_text`. +its contents can be retrieved using `ComboBoxTextExt::get_active_text`. The entry itself can be accessed by calling `BinExt::get_child` on the combo box. @@ -6189,19 +6849,27 @@ translation attributes “translatable”, “context” and “comments”. Here is a UI definition fragment specifying `ComboBoxText` items: -```text - - - Factory - Home - Subway - - +```plain +combobox +╰── box.linked + ├── entry.combo + ├── button.combo + ╰── window.popup ``` +`ComboBoxText` 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. + # Implements -[`ComboBoxExt`](trait.ComboBoxExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html) +[`ComboBoxTextExt`](trait.ComboBoxTextExt.html), [`ComboBoxExt`](trait.ComboBoxExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html) + +Trait containing all `ComboBoxText` methods. + +# Implementors + +[`ComboBoxText`](struct.ComboBoxText.html) Creates a new `ComboBoxText`, which is a `ComboBox` just displaying strings. @@ -6216,24 +6884,24 @@ strings. The combo box created by this function has an entry. # Returns a new `ComboBoxText` - + Appends `text` to the list of strings stored in `self`. If `id` is non-`None` then it is used as the ID of the row. -This is the same as calling `ComboBoxText::insert` with a +This is the same as calling `ComboBoxTextExt::insert` with a position of -1. ## `id` a string ID for this value, or `None` ## `text` A string - + Appends `text` to the list of strings stored in `self`. -This is the same as calling `ComboBoxText::insert_text` with a +This is the same as calling `ComboBoxTextExt::insert_text` with a position of -1. ## `text` A string - + Returns the currently active string in `self`, or `None` if none is selected. If `self` contains an entry, this function will return its contents (which will not necessarily @@ -6243,7 +6911,7 @@ be an item from the list). a newly allocated string containing the currently active text. Must be freed with `g_free`. - + Inserts `text` at `position` in the list of strings stored in `self`. If `id` is non-`None` then it is used as the ID of the row. See `ComboBox:id-column`. @@ -6255,39 +6923,39 @@ An index to insert `text` a string ID for this value, or `None` ## `text` A string to display - + Inserts `text` at `position` in the list of strings stored in `self`. If `position` is negative then `text` is appended. -This is the same as calling `ComboBoxText::insert` with a `None` +This is the same as calling `ComboBoxTextExt::insert` with a `None` ID string. ## `position` An index to insert `text` ## `text` A string - + Prepends `text` to the list of strings stored in `self`. If `id` is non-`None` then it is used as the ID of the row. -This is the same as calling `ComboBoxText::insert` with a +This is the same as calling `ComboBoxTextExt::insert` with a position of 0. ## `id` a string ID for this value, or `None` ## `text` a string - + Prepends `text` to the list of strings stored in `self`. -This is the same as calling `ComboBoxText::insert_text` with a +This is the same as calling `ComboBoxTextExt::insert_text` with a position of 0. ## `text` A string - + Removes the string at `position` from `self`. ## `position` Index of the item to remove - + Removes all the text entries from the combo box. A GTK+ user interface is constructed by nesting widgets inside widgets. @@ -6312,6 +6980,16 @@ sizes and positions to their children. For example, a `HBox` arranges its children in a horizontal row, and a `Grid` arranges the widgets it contains in a two-dimensional grid. +For implementations of `Container` the virtual method `ContainerClass.forall`() +is always required, since it's used for drawing and other internal operations +on the children. +If the `Container` implementation expect to have non internal children +it's needed to implement both `ContainerClass.add`() and `ContainerClass.remove`(). +If the `Container` implementation has internal children, they should be added +with `WidgetExt::set_parent` on `init` and removed with `WidgetExt::unparent` +in the `WidgetClass.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. @@ -6333,11 +7011,11 @@ 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 `Widget::get_preferred_width` and then through `Widget::get_preferred_height_for_width`. +through `WidgetExt::get_preferred_width` and then through `WidgetExt::get_preferred_height_for_width`. When handling requests in the opposite `SizeRequestMode` it is important that every widget request at least enough space to display all of its content at all times. -When `Widget::get_preferred_height` is called on a container that is height-for-width, +When `WidgetExt::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: @@ -6372,7 +7050,7 @@ foo_container_get_preferred_height (GtkWidget *widget, } ``` -Similarly, when `Widget::get_preferred_width_for_height` is called for a container or widget +Similarly, when `WidgetExt::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: @@ -6401,15 +7079,15 @@ foo_container_get_preferred_width_for_height (GtkWidget *widget, 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 -`Widget::get_preferred_width` for each of its children. +`WidgetExt::get_preferred_width` for each of its children. For each potential group of children that are lined up horizontally, the values returned by -`Widget::get_preferred_width` should be collected in an array of `RequestedSize` structures. +`WidgetExt::get_preferred_width` should be collected in an array of `RequestedSize` 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 -`Widget::get_preferred_height_for_width` and using the sizes stored in the `RequestedSize` array. +`WidgetExt::get_preferred_height_for_width` and using the sizes stored in the `RequestedSize` 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 @@ -6448,7 +7126,7 @@ To set the value of a child property, use `Container::child_set_property`, To obtain the value of a child property, use `Container::child_get_property`, `ContainerExt::child_get` or `ContainerExt::child_get_valist`. To emit notification about child property -changes, use `Widget::child_notify`. +changes, use `WidgetExt::child_notify`. # `Container` as `Buildable` @@ -6499,7 +7177,7 @@ such as `Window`, `Frame`, or `Button`; for more complicated layout containers such as `Box` or `Grid`, this function will pick default packing parameters that may not be correct. So consider functions such as `BoxExt::pack_start` and -`Grid::attach` as an alternative to `ContainerExt::add` in +`GridExt::attach` as an alternative to `ContainerExt::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. @@ -6541,16 +7219,30 @@ return location for the first property, followed Emits a `Widget::child-notify` signal for the [child property][child-properties] -`child_property` on widget. +`child_property` on the child. -This is an analogue of `gobject::Object::notify` for child properties. +This is an analogue of `gobject::ObjectExt::notify` for child properties. -Also see `Widget::child_notify`. +Also see `WidgetExt::child_notify`. ## `child` the child widget ## `child_property` the name of a child property installed on the class of `self` + +Emits a `Widget::child-notify` signal for the +[child property][child-properties] specified by +`pspec` on the child. + +This is an analogue of `gobject::ObjectExt::notify_by_pspec` for child properties. + +Feature: `v3_18` + +## `child` +the child widget +## `pspec` +the `gobject::ParamSpec` of a child property instealled on + the class of `self` Sets one or more child properties for `child` and `self`. ## `child` @@ -6585,21 +7277,28 @@ children. a `glib::Type`. -Invokes `callback` on each child of `self`, 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 `ContainerExt::foreach`, -rather than `ContainerExt::forall`. +Invokes `callback` on each direct child of `self`, 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 `ContainerExt::foreach`, rather +than `ContainerExt::forall`. ## `callback` a callback ## `callback_data` callback user data -Invokes `callback` on each non-internal child of `self`. See -`ContainerExt::forall` for details on what constitutes an -“internal” child. Most applications should use -`ContainerExt::foreach`, rather than `ContainerExt::forall`. +Invokes `callback` on each non-internal child of `self`. +See `ContainerExt::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. + +Most applications should use `ContainerExt::foreach`, +rather than `ContainerExt::forall`. ## `callback` a callback ## `callback_data` @@ -6639,12 +7338,12 @@ has been set explicitly. Returns the current focus child widget inside `self`. This is not the currently focused widget. That can be obtained by calling -`Window::get_focus`. +`WindowExt::get_focus`. # Returns The child widget which will receive the - focus inside `self` when the `conatiner` is focussed, + focus inside `self` when the `self` is focused, or `None` if none is set. Retrieves the horizontal focus adjustment for the container. See @@ -6660,8 +7359,8 @@ Retrieves the vertical focus adjustment for the container. See # Returns -the vertical focus adjustment, or `None` if - none has been set. +the vertical focus adjustment, or + `None` if none has been set. Returns a newly created widget path representing all the widget hierarchy from the toplevel down to and including `child`. @@ -6695,7 +7394,7 @@ the `cr` the container received. `ContainerExt::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 -`Widget::draw` on the child directly. +`WidgetExt::draw` on the child directly. In most cases, a container can simply either inherit the `Widget::draw` implementation from `Container`, or do some drawing @@ -6711,10 +7410,10 @@ Removes `widget` from `self`. `widget` must be inside `self`. Note that `self` 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 while it’s not inside -a container, using `gobject::Object::ref`. If you don’t want to use `widget` +again, you need to add a reference to it before removing it from +a container, using `gobject::ObjectExt::ref`. If you don’t want to use `widget` again it’s usually more efficient to simply destroy it directly -using `Widget::destroy` since this will remove it from the +using `WidgetExt::destroy` since this will remove it from the container and help break any circular reference count cycles. ## `widget` a current child of `self` @@ -6754,14 +7453,14 @@ This function emits the `Container`::set_focus_child signal of default behaviour by overriding the class closure of this signal. This is function is mostly meant to be used by widgets. Applications can use -`Widget::grab_focus` to manually set the focus to a specific widget. +`WidgetExt::grab_focus` to manually set the focus to a specific widget. ## `child` a `Widget`, or `None` 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 `ScrolledWindow::get_hadjustment` for a typical way of obtaining +See `ScrolledWindowExt::get_hadjustment` for a typical way of obtaining the adjustment and `ContainerExt::set_focus_vadjustment` for setting the vertical adjustment. @@ -6774,7 +7473,7 @@ an adjustment which should be adjusted when the focus is 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 -`ScrolledWindow::get_vadjustment` for a typical way of obtaining +`ScrolledWindowExt::get_vadjustment` for a typical way of obtaining the adjustment and `ContainerExt::set_focus_hadjustment` for setting the horizontal adjustment. @@ -6791,7 +7490,7 @@ redrawn if any of their children changed allocation. # Deprecated since 3.14 -Call `Widget::queue_draw` in your size_allocate handler. +Call `WidgetExt::queue_draw` in your size_allocate handler. ## `needs_redraws` the new value for the container’s `reallocate_redraws` flag @@ -6828,7088 +7527,8281 @@ Place the scrollbars on the top and left of the widget. `CssProvider` is an object implementing the `StyleProvider` interface. -It is able to parse [CSS-like](http://www.w3.org/TR/CSS2) -input in order to style widgets. - -## Default files - -An application can cause GTK+ to parse a specific CSS style sheet by -calling `CssProvider::load_from_file` and adding the provider with -`StyleContext::add_provider` or `StyleContext::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+ tries to load -`$HOME/.themes/theme-name/gtk-3.0/gtk.css`, -falling back to -`datadir/share/themes/theme-name/gtk-3.0/gtk.css`, -where theme-name is the name of the current theme -(see the `Settings:gtk-theme-name` setting) and datadir -is the prefix configured when GTK+ was compiled, unless overridden by the -`GTK_DATA_PREFIX` environment variable. - -# Style sheets - -The basic structure of the style sheets understood by this provider is -a series of statements, which are either rule sets or “@-rules”, separated -by whitespace. - -A rule set consists of a selector and a declaration block, which is -a series of declarations enclosed in curly braces ({ and }). The -declarations are separated by semicolons (;). Multiple selectors can -share the same declaration block, by putting all the separators in -front of the block, separated by commas. - -An example of a rule set with two selectors: - -```text -GtkButton, GtkEntry { - color: #ff00ea; - font: Comic Sans 12 -} -``` +It is able to parse [CSS-like][css-overview] input in order to style widgets. -# Selectors # {`gtkcssprovider`-selectors} - -Selectors work very similar to the way they do in CSS, with widget class -names taking the role of element names, and widget names taking the role -of IDs. When used in a selector, widget names must be prefixed with a -'#' character. The “*” character represents the so-called universal -selector, which matches any widget. - -To express more complicated situations, selectors can be combined in -various ways: -- To require that a widget satisfies several conditions, - combine several selectors into one by concatenating them. E.g. - `GtkButton#button1` matches a `Button` widget - with the name button1. -- To only match a widget when it occurs inside some other - widget, write the two selectors after each other, separated by whitespace. - E.g. `GtkToolBar GtkButton` matches `Button` widgets - that occur inside a `GtkToolBar`. -- In the previous example, the `Button` is matched even - if it occurs deeply nested inside the toolbar. To restrict the match - to direct children of the parent widget, insert a “>” character between - the two selectors. E.g. `GtkNotebook > GtkLabel` matches - `Label` widgets that are direct children of a `Notebook`. - -## Examples of widget classes and names in selectors - -Theme labels that are descendants of a window: - -```text -GtkWindow GtkLabel { - background-color: #898989 -} -``` +An application can make GTK+ parse a specific CSS style sheet by calling +`CssProviderExt::load_from_file` or `CssProviderExt::load_from_resource` +and adding the provider with `StyleContextExt::add_provider` or +`StyleContext::add_provider_for_screen`. -Theme notebooks, and anything that’s within these: +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-name/gtk-VERSION/gtk.css`, +`$HOME/.themes/theme-name/gtk-VERSION/gtk.css`, +`$XDG_DATA_DIRS/themes/theme-name/gtk-VERSION/gtk.css` and +`DATADIR/share/themes/THEME/gtk-VERSION/gtk.css`, where `THEME` is the name of +the current theme (see the `Settings: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 `Settings:gtk-key-theme-name`. -```text -GtkNotebook { - background-color: #a939f0 -} -``` +# Implements -Theme combo boxes, and entries that are direct children of a notebook: +[`CssProviderExt`](trait.CssProviderExt.html), [`ObjectExt`](trait.ObjectExt.html), [`StyleProviderExt`](trait.StyleProviderExt.html) + +Trait containing all `CssProvider` methods. -```text -GtkComboBox, -GtkNotebook > GtkEntry { - color: @fg_color; - background-color: #1209a2 -} -``` +# Implementors -Theme any widget within a `Bin`: +[`CssProvider`](struct.CssProvider.html) + +Returns a newly created `CssProvider`. -```text -GtkBin * { - font: Sans 20 -} -``` +# Returns -Theme a label named title-label: +A new `CssProvider` + +Returns the provider containing the style settings used as a +fallback for all widgets. -```text -GtkLabel#title-label { - font: Sans 15 -} -``` +# Returns -Theme any widget named main-entry: +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 +## `name` +A theme name +## `variant` +variant to load, for example, "dark", or + `None` for the default -```text -#main-entry { - background-color: #f0a810 -} -``` +# Returns -Widgets may also define style classes, which can be used for matching. -When used in a selector, style classes must be prefixed with a “.” -character. +a `CssProvider` with the theme loaded. + This memory is owned by GTK+, and you must not free it. + +Loads `data` into `self`, and by doing so clears any previously loaded +information. +## `data` +CSS data loaded in memory +## `length` +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. -Refer to the documentation of individual widgets to learn which -style classes they define and see -[Style Classes and Regions][gtkstylecontext-classes] -for a list of all style classes used by GTK+ widgets. +# Returns -Note that there is some ambiguity in the selector syntax when it comes -to differentiation widget class names from regions. GTK+ currently treats -a string as a widget class name if it contains any uppercase characters -(which should work for more widgets with names like `Label`). +`true`. The return value is deprecated and `false` will only be + returned for backwards compatibility reasons if an `error` is not + `None` and a loading error occurred. To track errors while loading + CSS, connect to the `CssProvider::parsing-error` signal. + +Loads the data contained in `file` into `self`, making it +clear any previously loaded information. +## `file` +`gio::File` pointing to a file to load -## Examples for style classes in selectors +# Returns -Theme all widgets defining the class entry: +`true`. The return value is deprecated and `false` will only be + returned for backwards compatibility reasons if an `error` is not + `None` and a loading error occurred. To track errors while loading + CSS, connect to the `CssProvider::parsing-error` signal. + +Loads the data contained in `path` into `self`, making it clear +any previously loaded information. +## `path` +the path of a filename to load, in the GLib filename encoding -```text -.entry { - color: #39f1f9; -} -``` +# Returns -Theme spinbuttons’ entry: +`true`. The return value is deprecated and `false` will only be + returned for backwards compatibility reasons if an `error` is not + `None` and a loading error occurred. To track errors while loading + CSS, connect to the `CssProvider::parsing-error` signal. + +Loads the data contained in the resource at `resource_path` into +the `CssProvider`, clearing any previously loaded information. -```text -GtkSpinButton.entry { - color: #900185 -} -``` +To track errors while loading CSS, connect to the +`CssProvider::parsing-error` signal. -In complicated widgets like e.g. a `Notebook`, it may be desirable -to style different parts of the widget differently. To make this -possible, container widgets may define regions, whose names -may be used for matching in selectors. +Feature: `v3_16` -Some containers allow to further differentiate between regions by -applying so-called pseudo-classes to the region. For example, the -tab region in `Notebook` allows to single out the first or last -tab by using the :first-child or :last-child pseudo-class. -When used in selectors, pseudo-classes must be prefixed with a -':' character. +## `resource_path` +a `gio::Resource` resource path + +Converts the `self` into a string representation in CSS +format. -Refer to the documentation of individual widgets to learn which -regions and pseudo-classes they define and see -[Style Classes and Regions][gtkstylecontext-classes] -for a list of all regions -used by GTK+ widgets. +Using `CssProviderExt::load_from_data` with the return value +from this function on a new provider created with +`CssProvider::new` will basically create a duplicate of +this `self`. -## Examples for regions in selectors +# Returns -Theme any label within a notebook: +a new string representing the `self`. + +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 `CssSection::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 +`self` is not yet parsed completely. This will for example +happen in the `CssProvider`::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. -```text -GtkNotebook GtkLabel { - color: #f90192; -} -``` +# Returns -Theme labels within notebook tabs: +the line number + +Returns the offset in bytes from the start of the current line +returned via `CssSection::get_end_line`. +This value may change in future invocations of this function if +`self` is not yet parsed completely. This will for example +happen in the `CssProvider`::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. -```text -GtkNotebook tab GtkLabel { - color: #703910; -} -``` +# Returns -Theme labels in the any first notebook tab, both selectors are -equivalent: +the offset in bytes from the start of the line. + +Gets the file that `self` was parsed from. If no such file exists, +for example because the CSS was loaded via +`CssProviderExt::load_from_data`(), then `None` is returned. -```text -GtkNotebook tab:nth-child(first) GtkLabel, -GtkNotebook tab:first-child GtkLabel { - color: #89d012; -} -``` +# Returns -Another use of pseudo-classes is to match widgets depending on their -state. This is conceptually similar to the :hover, :active or :focus -pseudo-classes in CSS. The available pseudo-classes for widget states -are :active, :prelight (or :hover), :insensitive, :selected, :focused -and :inconsistent. +the `gio::File` that `self` was parsed from + or `None` if `self` was parsed from other data + +Gets the parent section for the given `self`. The parent section is +the section that contains this `self`. A special case are sections of +type `CssSectionType::Document`. Their parent will either be `None` +if they are the original CSS document that was loaded by +`CssProviderExt::load_from_file` or a section of type +`CssSectionType::Import` if it was loaded with an import rule from +a different file. -## Examples for styling specific widget states +# Returns -Theme active (pressed) buttons: +the parent section or `None` if none + +Gets the type of information that `self` describes. -```text -GtkButton:active { - background-color: #0274d9; -} -``` +# Returns -Theme buttons with the mouse pointer on it, both are equivalent: +the type of `self` + +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. -```text -GtkButton:hover, -GtkButton:prelight { - background-color: #3085a9; -} -``` +# Returns -Theme insensitive widgets, both are equivalent: +the line number + +Returns the offset in bytes from the start of the current line +returned via `CssSection::get_start_line`. -```text -:insensitive, -*:insensitive { - background-color: #320a91; -} -``` +# Returns -Theme selection colors in entries: +the offset in bytes from the start of the line. + +Increments the reference count on `self`. -```text -GtkEntry:selected { - background-color: #56f9a0; -} -``` +# Returns -Theme focused labels: +`self` itself. + +Decrements the reference count on `self`, freeing the +structure if the reference count reaches 0. + +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. -```text -GtkLabel:focused { - background-color: #b4940f; -} -``` +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 `CssSection::get_parent` + might return `None`. + +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: `Entry::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. + +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. -Theme inconsistent checkbuttons: +GTK+ treats a dialog as a window split vertically. The top section is a +`VBox`, and is where widgets such as a `Label` or a `Entry` 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. -```text -GtkCheckButton:inconsistent { - background-color: #20395a; -} -``` +`Dialog` boxes are created with a call to `Dialog::new` or +`Dialog::new_with_buttons`. `Dialog::new_with_buttons` is +recommended; it allows you to set the dialog title, some convenient +flags, and add simple buttons. -Widget state pseudoclasses may only apply to the last element -in a selector. +If “dialog” is a newly created dialog, the two primary areas of the +window can be accessed through `DialogExt::get_content_area` and +`DialogExt::get_action_area`, as can be seen from the example below. -To determine the effective style for a widget, all the matching rule -sets are merged. As in CSS, rules apply by specificity, so the rules -whose selectors more closely match a widget path will take precedence -over the others. +A “modal” dialog (that is, one which freezes the rest of the application +from user input), can be created by calling `WindowExt::set_modal` on the +dialog. Use the GTK_WINDOW() macro to cast the widget returned from +`Dialog::new` into a `Window`. When using `Dialog::new_with_buttons` +you can also pass the `DialogFlags::Modal` flag to make a dialog modal. -# @ Rules +If you add buttons to `Dialog` using `Dialog::new_with_buttons`, +`DialogExt::add_button`, `DialogExt::add_buttons`, or +`DialogExt::add_action_widget`, clicking the button will emit a signal +called `Dialog::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 +`ResponseType` enumeration (these all have values less than zero). If +a dialog receives a delete event, the `Dialog::response` signal will +be emitted with a response ID of `ResponseType::DeleteEvent`. -GTK+’s CSS supports the \@import rule, in order to load another -CSS style sheet in addition to the currently parsed one. +If you want to block waiting for a dialog to return before returning +control flow to your code, you can call `DialogExt::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. -An example for using the \@import rule: +For the simple dialog in the following example, in reality you’d probably +use `MessageDialog` 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. -```text -@import url ("path/to/common.css"); -``` +An example for simple `Dialog` usage: -In order to extend key bindings affecting different widgets, GTK+ -supports the \@binding-set rule to parse a set of bind/unbind -directives, see `BindingSet` for the supported syntax. Note that -the binding sets defined in this way must be associated with rule sets -by setting the gtk-key-bindings style property. +```C +// Function to open a dialog box with a message +void +quick_message (GtkWindow *parent, gchar *message) +{ + GtkWidget *dialog, *label, *content_area; + GtkDialogFlags flags; -Customized key bindings are typically defined in a separate -`gtk-keys.css` CSS file and GTK+ loads this file -according to the current key theme, which is defined by the -`Settings:gtk-key-theme-name` setting. + // 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); -An example for using the \@binding rule: + // Ensure that the dialog box is destroyed when the user responds -```text -@binding-set binding-set1 { - bind "Left" { "move-cursor" (visual-positions, -3, 0) }; - unbind "End"; -}; + g_signal_connect_swapped (dialog, + "response", + G_CALLBACK (gtk_widget_destroy), + dialog); -@binding-set binding-set2 { - bind "Right" { "move-cursor" (visual-positions, 3, 0) }; - bind "KP_space" { "delete-from-cursor" (whitespace, 1) - "insert-at-cursor" (" ") }; -}; + // Add the label, and show everything we’ve added -GtkEntry { - gtk-key-bindings: binding-set1, binding-set2; + gtk_container_add (GTK_CONTAINER (content_area), label); + gtk_widget_show_all (dialog); } ``` -GTK+ also supports an additional \@define-color rule, in order -to define a color name which may be used instead of color numeric -representations. Also see the `Settings:gtk-color-scheme` setting -for a way to override the values of these named colors. - -An example for defining colors: - -```text -@define-color bg_color #f9a039; +# `Dialog` as `Buildable` -* { - background-color: @bg_color; -} -``` +The `Dialog` implementation of the `Buildable` interface exposes the +`vbox` and `action_area` as internal children with the names “vbox” and +“action_area”. -# Symbolic colors +`Dialog` supports a custom `` element, which can contain +multiple `` 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 `` element +to true. -Besides being able to define color names, the CSS parser is also able -to read different color expressions, which can also be nested, providing -a rich language to define colors which are derived from a set of base -colors. +`Dialog` supports adding action widgets by specifying “action“ as +the “type“ attribute of a `` 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 `` element. -An example for using symbolic colors: +An example of a `Dialog` UI definition fragment: ```text -@define-color entry-color shade (@bg_color, 0.7); - -GtkEntry { - background-color: @entry-color; -} - -GtkEntry:focused { - background-color: mix (@entry-color, - shade (#fff, 0.5), - 0.8); -} + + + + + + + True + + + + button_cancel + button_ok + + ``` -# Specifying Colors # {`specifying`-colors} -There are various ways to express colors in GTK+ CSS. - -## rgb(r, g, b) - -An opaque color. +# Implements -- `r`, `g`, `b` can be either integers between 0 and 255, or percentages. +[`DialogExt`](trait.DialogExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `Dialog` methods. +# Implementors -```text - color: rgb(128, 10, 54); - background-color: rgb(20%, 30%, 0%); -``` +[`AboutDialog`](struct.AboutDialog.html), [`AppChooserDialog`](struct.AppChooserDialog.html), [`ColorChooserDialog`](struct.ColorChooserDialog.html), [`Dialog`](struct.Dialog.html), [`FileChooserDialog`](struct.FileChooserDialog.html), [`FontChooserDialog`](struct.FontChooserDialog.html), [`MessageDialog`](struct.MessageDialog.html), [`RecentChooserDialog`](struct.RecentChooserDialog.html) + +Creates a new dialog box. -## rgba(r, g, b, a) +Widgets should not be packed into this `Window` +directly, but into the `vbox` and `action_area`, as described above. -A translucent color. +# Returns -- `r`, `g`, `b` can be either integers between 0 and 255, or percentages. -- `a` is a floating point number between 0 and 1. +the new dialog as a `Widget` + +Creates a new `Dialog` with title `title` (or `None` for the default +title; see `WindowExt::set_title`) and transient parent `parent` (or +`None` for none; see `WindowExt::set_transient_for`). The `flags` +argument can be used to make the dialog modal (`DialogFlags::Modal`) +and/or to have it destroyed along with its transient parent +(`DialogFlags::DestroyWithParent`). After `flags`, button +text/response ID pairs should be listed, with a `None` 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 `ResponseType` +enumeration. If the user clicks one of these dialog buttons, +`Dialog` will emit the `Dialog::response` signal with the corresponding +response ID. If a `Dialog` receives the `Widget::delete-event` signal, +it will emit ::response with a response ID of `ResponseType::DeleteEvent`. +However, destroying a dialog does not emit the ::response signal; +so be careful relying on ::response when using the +`DialogFlags::DestroyWithParent` 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: -```text - color: rgb(128, 10, 54, 0.5); +```C + 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); ``` +## `title` +Title of the dialog, or `None` +## `parent` +Transient parent of the dialog, or `None` +## `flags` +from `DialogFlags` +## `first_button_text` +text to go in first button, or `None` -## \#xxyyzz +# Returns -An opaque color. +a new `Dialog` + +Adds an activatable widget to the action area of a `Dialog`, +connecting a signal handler that will emit the `Dialog::response` +signal on the dialog when the widget is activated. The widget is +appended to the end of the dialog’s action area. If you want to add a +non-activatable widget, simply pack it into the `action_area` field +of the `Dialog` struct. +## `child` +an activatable widget +## `response_id` +response ID for `child` + +Adds a button with the given text and sets things up so that +clicking the button will emit the `Dialog::response` signal with +the given `response_id`. The button is appended to the end of the +dialog’s action area. The button widget is returned, but usually +you don’t need it. +## `button_text` +text of button +## `response_id` +response ID for the button -- `xx`, `yy`, `zz` are hexadecimal numbers specifying `r`, `g`, `b` - variants with between 1 and 4 hexadecimal digits per component. +# Returns +the `Button` widget that was added + +Adds more buttons, same as calling `DialogExt::add_button` +repeatedly. The variable argument list should be `None`-terminated +as with `Dialog::new_with_buttons`. Each button must have both +text and response ID. +## `first_button_text` +button text + +Returns the action area of `self`. -```text - color: #f0c; - background-color: #ff00cc; - border-color: #ffff0000cccc; -``` +# Deprecated since 3.12 -## \@name +Direct access to the action area + is discouraged; use `DialogExt::add_button`, etc. -Reference to a color that has been defined with \@define-color +# Returns +the action area + +Returns the content area of `self`. -```text - color: @bg_color; -``` +# Returns -## mix(color1, color2, factor) +the content area `Box`. + +Returns the header bar of `self`. Note that the +headerbar is only used by the dialog if the +`Dialog:use-header-bar` property is `true`. -A linear combination of `color1` and `color2`. +Feature: `v3_12` -- `factor` is a floating point number between 0 and 1. +# Returns -```text - color: mix(#ff1e0a, @bg_color, 0.8); -``` +the header bar + +Gets the response id of a widget in the action area +of a dialog. +## `widget` +a widget in the action area of `self` -## shade(color, factor) +# Returns -A lighter or darker variant of `color`. +the response id of `widget`, or `ResponseType::None` + if `widget` doesn’t have a response id set. + +Gets the widget button that uses the given response ID in the action area +of a dialog. +## `response_id` +the response ID used by the `self` widget -- `factor` is a floating point number. +# Returns +the `widget` button that uses the given + `response_id`, or `None`. + +Emits the `Dialog::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 `DialogExt::run` will be monitoring the +::response signal and take appropriate action. +## `response_id` +response ID + +Blocks in a recursive main loop until the `self` either emits the +`Dialog::response` signal, or is destroyed. If the dialog is +destroyed during the call to `DialogExt::run`, `DialogExt::run` returns +`ResponseType::None`. Otherwise, it returns the response ID from the +::response signal emission. -```text - color: shade(@fg_color, 0.5); -``` +Before entering the recursive main loop, `DialogExt::run` calls +`WidgetExt::show` on the dialog for you. Note that you still +need to show any children of the dialog yourself. -## lighter(color) +During `DialogExt::run`, the default behavior of `Widget::delete-event` +is disabled; if the dialog receives ::delete_event, it will not be +destroyed as windows usually are, and `DialogExt::run` will return +`ResponseType::DeleteEvent`. Also, during `DialogExt::run` the dialog +will be modal. You can force `DialogExt::run` to return at any time by +calling `DialogExt::response` to emit the ::response signal. Destroying +the dialog during `DialogExt::run` is a very bad idea, because your +post-run code won’t know whether the dialog was destroyed or not. -A lighter variant of `color`. +After `DialogExt::run` returns, you are responsible for hiding or +destroying the dialog if you wish to do so. +Typical usage of this function might be: -```text - color: lighter(@fg_color); +```C + gint 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); ``` -## darker(color) - -A darker variant of `color`. - - -```text - color: darker(@bg_color); -``` +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 `DialogExt::run` call. -## alpha(color, factor) +# Returns -Modifies passed color’s alpha by a factor. +response ID + +Sets an alternative button order. If the +`Settings: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. -- `factor` is a floating point number. `factor` < 1.0 results in a more - transparent color while `factor` > 1.0 results in a more opaque color. +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: -```text - color: alpha(@fg_color, 0.5); -``` +```C +cancel_button = gtk_dialog_add_button (GTK_DIALOG (dialog), + _("_Cancel"), + GTK_RESPONSE_CANCEL); -# Gradients +ok_button = gtk_dialog_add_button (GTK_DIALOG (dialog), + _("_OK"), + GTK_RESPONSE_OK); -Linear or radial gradients can be used as background images. +gtk_widget_grab_default (ok_button); -## Linear Gradients +help_button = gtk_dialog_add_button (GTK_DIALOG (dialog), + _("_Help"), + GTK_RESPONSE_HELP); -A linear gradient along the line from (`start_x`, `start_y`) to -(`end_x`, `end_y`) is specified using the following syntax: +gtk_dialog_set_alternative_button_order (GTK_DIALOG (dialog), + GTK_RESPONSE_OK, + GTK_RESPONSE_CANCEL, + GTK_RESPONSE_HELP, + -1); +``` -> `-gtk-gradient (linear, start_x start_y, end_x end_y, color-stop (position, color), ...)` +# Deprecated since 3.10 -- `start_x` and `end_x` can be either a floating point number between -0 and 1, or one of the special values: “left”, “right”, or “center”. -- `start_y` and `end_y` can be either a floating point number between 0 and 1, or one -of the special values: “top”, “bottom” or “center”. -- `position` is a floating point number between 0 and 1. -- `color` is a color expression (see above). +Deprecated +## `first_response_id` +a response id used by one `self`’s buttons + +Sets an alternative button order. If the +`Settings: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`. -The color-stop can be repeated multiple times to add more than one color -stop. “from (color)” and “to (color)” can be used as abbreviations for -color stops with position 0 and 1, respectively. +See `DialogExt::set_alternative_button_order` for more information. -## Example: Linear Gradient -![](gradient1.png) +This function is for use by language bindings. -```text --gtk-gradient (linear, - left top, right bottom, - from(@yellow), to(@blue)); -``` +# Deprecated since 3.10 -## Example: Linear Gradient 2 -![](gradient2.png) +Deprecated +## `n_params` +the number of response ids in `new_order` +## `new_order` +an array of response ids of + `self`’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. +## `response_id` +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. +## `response_id` +a response ID +## `setting` +`true` for sensitive + +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 +`Widget::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 `DrawingArea` 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: -```text --gtk-gradient (linear, - 0 0, 0 1, - color-stop(0, @yellow), - color-stop(0.2, @blue), - color-stop(1, #0f0)) -``` +- Mouse and button press signals to respond to input from + the user. (Use `WidgetExt::add_events` to enable events + you wish to receive.) -## Radial Gradients +- The `Widget::realize` signal to take any necessary actions + when the widget is instantiated on a particular display. + (Create GDK resources in response to this signal.) -A radial gradient along the two circles defined by (`start_x`, -`start_y`, `start_radius`) and (`end_x`, `end_y`, `end_radius`) is -specified using the following syntax: +- The `Widget::size-allocate` signal to take any necessary + actions when the widget changes size. -> `-gtk-gradient (radial, start_x start_y, start_radius, end_x end_y, end_radius, color-stop (position, color), ...)` +- The `Widget::draw` signal to handle redrawing the + contents of the widget. -where `start_radius` and `end_radius` are floating point numbers -and the other parameters are as before. +The following code portion demonstrates using a drawing +area to display a circle in the normal widget foreground +color. -## Example: Radial Gradient -![](gradient3.png) +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. -```text --gtk-gradient (radial, - center center, 0, - center center, 1, - from(@yellow), to(@green)) -``` +## Simple `DrawingArea` usage -## Example: Radial Gradient 2 -![](gradient4.png) -```text --gtk-gradient (radial, - 0.4 0.4, 0.1, - 0.6 0.6, 0.7, - color-stop (0, #f00), - color-stop (0.1, #a0f), - color-stop (0.2, @yellow), - color-stop (1, @green)) -``` +```C +gboolean +draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data) +{ + guint width, height; + GdkRGBA color; + GtkStyleContext *context; -# Border images # {`border`-images} + context = gtk_widget_get_style_context (widget); -Images and gradients can also be used in slices for the purpose of creating -scalable borders. -For more information, see the [CSS3 documentation for the border-image property](http://www.w3.org/TR/css3-background/`border`-images). + width = gtk_widget_get_allocated_width (widget); + height = gtk_widget_get_allocated_height (widget); -![](slices.png) + gtk_render_background (context, cr, 0, 0, width, height); -The parameters of the slicing process are controlled by four -separate properties. + cairo_arc (cr, + width / 2.0, height / 2.0, + MIN (width, height) / 2.0, + 0, 2 * G_PI); -- Image Source -- Image Slice -- Image Width -- Image Repeat + gtk_style_context_get_color (context, + gtk_style_context_get_state (context), + &color); + gdk_cairo_set_source_rgba (cr, &color); -Note that you can use the `border-image` shorthand property to set -values for the properties at the same time. + cairo_fill (cr); -## Image Source + 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); +``` -The border image source can be specified either as a -URL or a gradient: +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; `WidgetExt::queue_draw_area` and +`gdk::WindowExt::invalidate_rect` are equally good ways to do this. +You’ll then get a draw signal for the invalid region. -```text - border-image-source: url(path); -``` -or +The available routines for drawing are documented on the +[GDK Drawing Primitives][gdk3-Cairo-Interaction] page +and the cairo documentation. -```text - border-image-source: -gtk-gradient(...); -``` +To receive mouse events on a drawing area, you will need to enable +them with `WidgetExt::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 `WidgetExt::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. -## Image Slice +# Implements +[`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Creates a new drawing area. -```text - border-image-slice: top right bottom left; -``` +# Returns -The sizes specified by the `top`, `right`, `bottom`, and `left` parameters -are the offsets (in pixels) from the relevant edge where the image -should be “cut off” to build the slices used for the rendering -of the border. +a new `DrawingArea` + +The `Editable` interface is an interface which should be implemented by +text editing widgets, such as `Entry` and `SpinButton`. It contains functions +for generically manipulating an editable widget, a large number of action +signals used for key bindings, and several signals that an application can +connect to to modify the behavior of a widget. -## Image Width +As an example of the latter usage, by connecting +the following handler to `Editable::insert-text`, an application +can convert all entry into a widget into uppercase. +## Forcing entry to uppercase. -```text - border-image-width: top right bottom left; -``` -The sizes specified by the `top`, `right`, `bottom` and `left` parameters -are inward distances from the border box edge, used to specify the -rendered size of each slice determined by border-image-slice. -If this property is not specified, the values of border-width will -be used as a fallback. +```C +#include ; -## Image Repeat +void +insert_text_handler (GtkEditable *editable, + const gchar *text, + gint length, + gint *position, + gpointer data) +{ + gchar *result = g_utf8_strup (text, length); -Specifies how the image slices should be rendered in the area -outlined by border-width. + 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"); -```text - border-image-repeat: [stretch|repeat|round|space]; + g_free (result); +} ``` -or -```text - border-image-repeat: [stretch|repeat|round|space] [stretch|repeat|round|space]; -``` +# Implements -- The default (stretch) is to resize the slice to fill in the -whole allocated area. +[`EditableExt`](trait.EditableExt.html) + +Trait containing all `Editable` methods. -- If the value of this property is “repeat”, the image slice will -be tiled to fill the area. +# Implementors -- If the value of this property is “round”, the image slice will be -tiled to fill the area, and scaled to fit it exactly a whole number -of times. +[`Editable`](struct.Editable.html), [`Entry`](struct.Entry.html), [`SearchEntry`](struct.SearchEntry.html), [`SpinButton`](struct.SpinButton.html) + +Copies the contents of the currently selected content in the editable and +puts it on the clipboard. + +Removes the contents of the currently selected content in the editable and +puts it on the clipboard. + +Deletes the currently selected text of the editable. +This call doesn’t do anything if there is no selected text. + +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. -- If the value of this property is “space”, the image slice will be -tiled to fill the area, and if it doesn’t fit it exactly a whole -number of times, the extra space is distributed as padding around -the slices. +Note that the positions are specified in characters, not bytes. +## `start_pos` +start position +## `end_pos` +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. -- If two options are specified, the first one affects the -horizontal behaviour and the second one the vertical behaviour. If -only one option is specified, it affects both. +Note that positions are specified in characters, not bytes. +## `start_pos` +start of text +## `end_pos` +end of text +# Returns -## Example: Border Image -![](border1.png) +a pointer to the contents of the widget as a + string. This string is allocated by the `Editable` + implementation and should be freed by the caller. + +Retrieves whether `self` is editable. See +`Editable::set_editable`. -```text -border-image: url("gradient1.png") 10 10 10 10; -``` +# Returns -## Example: Repeating Border Image -![](border2.png) +`true` if `self` is editable. + +Retrieves the current position of the cursor relative to the start +of the content of the editable. -```text -border-image: url("gradient1.png") 10 10 10 10 repeat; -``` +Note that this position is in characters, not in bytes. -## Example: Stetched Border Image -![](border3.png) +# Returns -```text -border-image: url("gradient1.png") 10 10 10 10 stretch; -``` +the cursor position + +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. +## `start_pos` +location to store the starting position, or `None` +## `end_pos` +location to store the end position, or `None` -# Supported Properties +# Returns -Properties are the part that differ the most to common CSS, not all -properties are supported (some are planned to be supported -eventually, some others are meaningless or don't map intuitively in -a widget based environment). +`true` if an area is selected, `false` otherwise + +Inserts `new_text_length` bytes of `new_text` into the contents of the +widget, at position `position`. -The currently supported properties are: +Note that the position is in characters, not in bytes. +The function updates `position` to point after the newly inserted text. +## `new_text` +the text to append +## `new_text_length` +the length of the text in bytes, or -1 +## `position` +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. + +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. -## engine: [name|none]; +Note that positions are specified in characters, not bytes. +## `start_pos` +start of region +## `end_pos` +end of region + +Determines if the user can edit the text in the editable +widget or not. +## `is_editable` +`true` if the user is allowed to edit the text + in the widget + +Sets the cursor position in the editable to the given value. -- `none` means to use the default (ie. builtin engine) +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. +## `position` +the position of the cursor + +The `Entry` 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. -```text - engine: clearlooks; -``` +When using an entry for passwords and other sensitive information, +it can be put into “password mode” using `EntryExt::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 +`EntryExt::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 +`Entry:caps-lock-warning` property. -## background-color: [color|transparent]; +Since 2.16, `Entry` has the ability to display progress or activity +information behind the text. To make an entry display such information, +use `EntryExt::set_progress_fraction` or `EntryExt::set_progress_pulse_step`. -- `color`: See [Specifying Colors][specifying-colors] +Additionally, `Entry` 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 `EntryExt::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 `Entry::icon-press` signal. To allow DND operations +from an icon, use `EntryExt::set_icon_drag_source`. To set a tooltip on +an icon, use `EntryExt::set_icon_tooltip_text` or the corresponding function +for markup. -```text - background-color: shade (@color1, 0.5); -``` +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. -## color: [color|transparent]; +# CSS nodes -- `color`: See [Specifying Colors][specifying-colors] -```text - color: #fff; +```plain +entry +├── image.left +├── image.right +├── undershoot.left +├── undershoot.right +├── [selection] +├── [progress[.pulse]] +╰── [window.popup] ``` -## border-color: [color|transparent]{1,4}; +`Entry` 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. -- `color`: See [Specifying Colors][specifying-colors] -- Four values used to specify: top right bottom left -- Three values used to specify: top vertical bottom -- Two values used to specify: horizontal vertical -- One value used to specify: color +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. -```text - border-color: red green blue; -``` +When the entry has a selection, it adds a subnode with the name selection. -## border-top-color: [color|transparent]; +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. -- `color`: See [Specifying Colors][specifying-colors] +The CSS node for a context menu is added as a subnode below entry as well. -```text - border-top-color: @borders; -``` +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. -## border-right-color: [color|transparent]; +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. -- `color`: See [Specifying Colors][specifying-colors] +# Implements -```text - border-right-color: @borders; -``` +[`EntryExt`](trait.EntryExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html), [`CellEditableExt`](trait.CellEditableExt.html), [`EditableExt`](trait.EditableExt.html) + +Trait containing all `Entry` methods. -## border-bottom-color: [color|transparent]; +# Implementors -- `color`: See [Specifying Colors][specifying-colors] +[`Entry`](struct.Entry.html), [`SearchEntry`](struct.SearchEntry.html), [`SpinButton`](struct.SpinButton.html) + +Creates a new entry. -```text - border-bottom-color: @borders; -``` +# Returns -## border-left-color: [color|transparent]; +a new `Entry`. + +Creates a new entry with the specified text buffer. +## `buffer` +The buffer to use for the new `Entry`. -- `color`: See [Specifying Colors][specifying-colors] +# Returns -```text - border-left-color: @borders; -``` +a new `Entry` + +Retrieves the value set by `EntryExt::set_activates_default`. -## font-family: name; +# Returns -The name of the font family or font name to use. +`true` if the entry will activate the default widget + +Gets the value set by `EntryExt::set_alignment`. -- Note: unlike the CSS2 Specification this does not support using a - prioritized list of font family names and/or generic family - names. +# Returns +the alignment + +Gets the attribute list that was set on the entry using +`EntryExt::set_attributes`, if any. -```text - font-family: Sans, Cantarell; -``` +Feature: `v3_6` -## font-style: [normal|oblique|italic]; -Selects between normal, italic and oblique faces within a font family. +# Returns +the attribute list, or `None` + if none was set. + +Get the `EntryBuffer` object which holds the text for +this widget. -```text - font-style: italic; -``` +# Returns -## font-variant: [normal|small-caps]; +A `EntryBuffer` object. + +Returns the auxiliary completion object currently in use by `self`. -In a small-caps font the lower case letters look similar to the -uppercase ones, but in a smaller size and with slightly different -proportions. +# Returns +The auxiliary completion object currently + in use by `self`. + +Returns the index of the icon which is the source of the current +DND operation, or -1. -```text - font-variant: normal; -``` +This function is meant to be used in a `Widget::drag-data-get` +callback. -## font-weight: [normal|bold|bolder|lighter|100|200|300|400|500|600|700|800|900]; +# Returns -Selects the weight of the font. The values '100' to '900' form an -ordered sequence, where each number indicates a weight that is at -least as dark as its predecessor. The keyword 'normal' is -synonymous with '400', and 'bold' is synonymous with -'700'. Keywords other than 'normal' and 'bold' have been shown to -be often confused with font names and a numerical scale was -therefore chosen for the 9-value list. -- Maps to `PANGO_TYPE_WEIGHT` +index of the icon which is the source of the current + DND operation, or -1. + +Retrieves the horizontal cursor adjustment for the entry. +See `EntryExt::set_cursor_hadjustment`. -```text - font-weight: bold; -``` +# Returns -## font-size: [absolute-size|relative-size|percentage]; +the horizontal cursor adjustment, or `None` + if none has been set. + +Gets the value set by `EntryExt::set_has_frame`. -- `absolute-size`: The size in normal size units like `px`, `pt`, - and `em`. Or symbolic sizes like `xx-small`, `x-small`, `small`, - `medium`, `large`, `x-large`, `xx-large`. -- `relative-size`: `larger` or `smaller` relative to the parent. -- `percentage`: A percentage difference from the nominal size. +# Returns -```text - font-size: 12px; -``` - -## font-stretch: [face] - -Selects a normal, condensed, or expanded face from a font family. +whether the entry has a beveled frame + +Returns whether the icon is activatable. +## `icon_pos` +Icon position -Absolute keyword values have the following ordering, from narrowest to widest: +# Returns -- ultra-condensed -- extra-condensed -- condensed -- semi-condensed -- normal -- semi-expanded -- expanded -- extra-expanded -- ultra-expanded +`true` if the icon is activatable. + +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. -## font: [family] [style] [variant] [stretch] [size]; +If the entry is not realized or has no icon at the given position, +`icon_area` is filled with zeros. -A shorthand for setting a few font properties at once. -- Supports any format accepted by `pango::FontDescription::from_string` -- Note: this is somewhat different from the CSS2 Specification for this property. +See also `EntryExt::get_text_area` +## `icon_pos` +Icon position +## `icon_area` +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 `self`’s top left corner. +If `x`, `y` doesn’t lie inside an icon, -1 is returned. +This function is intended for use in a `Widget::query-tooltip` +signal handler. +## `x` +the x coordinate of the position to find +## `y` +the y coordinate of the position to find -```text - font: Bold 11; -``` +# Returns -## margin: [length|percentage]{1,4}; +the index of the icon at the given position, or -1 + +Retrieves the `gio::Icon` used for the icon, or `None` if there is +no icon or if the icon was set by some other method (e.g., by +stock, pixbuf, or icon name). +## `icon_pos` +Icon position -A shorthand for setting the margin space required on all sides of -an element. -- Four values used to specify: top right bottom left -- Three values used to specify: top horizontal bottom -- Two values used to specify: vertical horizontal -- One value used to specify: margin +# Returns -```text - margin: 1em 2em 4em; -``` +A `gio::Icon`, or `None` if no icon is set + or if the icon is not a `gio::Icon` + +Retrieves the icon name used for the icon, or `None` if there is +no icon or if the icon was set by some other method (e.g., by +pixbuf, stock or gicon). +## `icon_pos` +Icon position -## margin-top: [length|percentage]; +# Returns -Sets the margin space required on the top of an element. +An icon name, or `None` if no icon is set or if the icon + wasn’t set from an icon name + +Retrieves the image used for the icon. -```text - margin-top: 10px; -``` +Unlike the other methods of setting and getting icon data, this +method will work regardless of whether the icon was set using a +`gdk_pixbuf::Pixbuf`, a `gio::Icon`, a stock item, or an icon name. +## `icon_pos` +Icon position -## margin-right: [length|percentage]; +# Returns -Sets the margin space required on the right of an element. +A `gdk_pixbuf::Pixbuf`, or `None` if no icon is + set for this position. + +Returns whether the icon appears sensitive or insensitive. +## `icon_pos` +Icon position -```text - margin-right: 0px; -``` +# Returns -## margin-bottom: [length|percentage]; +`true` if the icon is sensitive. + +Retrieves the stock id used for the icon, or `None` if there is +no icon or if the icon was set by some other method (e.g., by +pixbuf, icon name or gicon). -Sets the margin space required on the bottom of an element. +# Deprecated since 3.10 -```text - margin-bottom: 10px; -``` +Use `EntryExt::get_icon_name` instead. +## `icon_pos` +Icon position -## margin-left: [length|percentage]; +# Returns -Sets the margin space required on the left of an element. +A stock id, or `None` if no icon is set or if the icon + wasn’t set from a stock id + +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 `ImageType::Empty`. +## `icon_pos` +Icon position -```text - margin-left: 1em; -``` +# Returns -## padding: [length|percentage]{1,4}; +image representation being used + +Gets the contents of the tooltip on the icon at the specified +position in `self`. +## `icon_pos` +the icon position -A shorthand for setting the padding space required on all sides of -an element. The padding area is the space between the content of -the element and its border. -- Four values used to specify: top right bottom left -- Three values used to specify: top horizontal bottom -- Two values used to specify: vertical horizontal -- One value used to specify: padding +# Returns -```text - padding: 1em 2em 4em; -``` +the tooltip text, or `None`. Free the returned + string with `g_free` when done. + +Gets the contents of the tooltip on the icon at the specified +position in `self`. +## `icon_pos` +the icon position -## padding-top: [length|percentage]; +# Returns -Sets the padding space required on the top of an element. +the tooltip text, or `None`. Free the returned + string with `g_free` when done. + +This function returns the entry’s `Entry:inner-border` property. See +`Entry::set_inner_border` for more information. -```text - padding-top: 10px; -``` +# Deprecated since 3.4 -## padding-right: [length|percentage]; +Use the standard border and padding CSS properties (through + objects like `StyleContext` and `CssProvider`); the value returned by + this function is ignored by `Entry`. -Sets the padding space required on the right of an element. +# Returns -```text - padding-right: 0px; -``` +the entry’s `Border`, or + `None` if none was set. + +Gets the value of the `Entry:input-hints` property. -## padding-bottom: [length|percentage]; +Feature: `v3_6` -Sets the padding space required on the bottom of an element. + +Gets the value of the `Entry:input-purpose` property. -```text - padding-bottom: 10px; -``` +Feature: `v3_6` -## padding-left: [length|percentage]; + +Retrieves the character displayed in place of the real characters +for entries with visibility set to false. See `EntryExt::set_invisible_char`. -Sets the padding space required on the left of an element. +# Returns -```text - padding-left: 1em; -``` +the current invisible char, or 0, if the entry does not + show invisible text at all. + +Gets the `pango::Layout` used to display the entry. +The layout is useful to e.g. convert text positions to +pixel positions, in combination with `EntryExt::get_layout_offsets`. +The returned layout is owned by the entry and must not be +modified or freed by the caller. -## border-width: [width]{1,4}; +Keep in mind that the layout text may contain a preedit string, so +`EntryExt::layout_index_to_text_index` and +`EntryExt::text_index_to_layout_index` are needed to convert byte +indices in the layout to byte indices in the entry contents. -A shorthand for setting the border width on all sides of -an element. -- Four values used to specify: top right bottom left -- Three values used to specify: top vertical bottom -- Two values used to specify: horizontal vertical -- One value used to specify: width +# Returns -```text - border-width: 1px 2px 4px; -``` +the `pango::Layout` for this entry + +Obtains the position of the `pango::Layout` 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. -## border-top-width: [width]; +Also useful to convert mouse events into coordinates inside the +`pango::Layout`, e.g. to take some action if some part of the entry text +is clicked. -Sets the border width required on the top of an element. +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 `pango::Layout` +functions you need to convert to and from pixels using +PANGO_PIXELS() or `PANGO_SCALE`. -```text - border-top: 10px; -``` +Keep in mind that the layout text may contain a preedit string, so +`EntryExt::layout_index_to_text_index` and +`EntryExt::text_index_to_layout_index` are needed to convert byte +indices in the layout to byte indices in the entry contents. +## `x` +location to store X offset of layout, or `None` +## `y` +location to store Y offset of layout, or `None` + +Retrieves the maximum allowed length of the text in +`self`. See `EntryExt::set_max_length`. -## border-right-width: [width]; +This is equivalent to: -Sets the border width required on the right of an element. -```text - border-right: 0px; +```C +GtkEntryBuffer *buffer; +buffer = gtk_entry_get_buffer (entry); +gtk_entry_buffer_get_max_length (buffer); ``` -## border-bottom-width: [width]; - -Sets the border width required on the bottom of an element. - -```text - border-bottom: 10px; -``` +# Returns -## border-left-width: [width]; +the maximum allowed number of characters + in `Entry`, or 0 if there is no maximum. + +Retrieves the desired maximum width of `self`, in characters. +See `EntryExt::set_max_width_chars`. -Sets the border width required on the left of an element. +Feature: `v3_12` -```text - border-left: 1em; -``` -## border-radius: [length|percentage]{1,4}; +# Returns -Allows setting how rounded all border corners are. -- Four values used to specify: top-left top-right bottom-right bottom-left -- Three values used to specify: top-left top-right-and-bottom-left bottom-right -- Two values used to specify: top-left-and-bottom-right top-right-and-bottom-left -- One value used to specify: radius on all sides +the maximum width of the entry, in characters + +Gets the value set by `EntryExt::set_overwrite_mode`. -```text - border-radius: 8px -``` +# Returns -## border-style: [none|solid|inset|outset]{1,4}; +whether the text is overwritten when typing. + +Retrieves the text that will be displayed when `self` is empty and unfocused -A shorthand property for setting the line style for all four sides -of the elements border. -- Four values used to specify: top right bottom left; -- Three values used to specify: top horizontal bottom -- Two values used to specify: vertical horizontal -- One value used to specify: style +# Returns -```text - border-style: solid; -``` +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. + +Returns the current fraction of the task that’s been completed. +See `EntryExt::set_progress_fraction`. -## border-image: [source] [slice] [ / width ] [repeat]; A shorthand -for setting an image on the borders of elements. See [Border -Images][border-images]. +# Returns -```text - border-image: url("/path/to/image.png") 3 4 4 3 repeat stretch; -``` +a fraction from 0.0 to 1.0 + +Retrieves the pulse step set with `EntryExt::set_progress_pulse_step`. -## border-image-source: [none|url|linear-gradient]{1,4}; +# Returns -Defines the image to use instead of the style of the border. If -this property is set to none, the style defined by border-style is -used instead. +a fraction from 0.0 to 1.0 + +Gets the tabstops that were set on the entry using `EntryExt::set_tabs`, if +any. -```text - border-image-source: url("/path/to/image.png"); -``` +Feature: `v3_10` -## border-image-slice: [number|percentage]{1,4}; -Divides the image specified by border-image-source in nine regions: -the four corners, the four edges and the middle. It does this by -specifying 4 inwards offsets. -- Four values used to specify: top right bottom left; -- Three values used to specify: top vertical bottom -- Two values used to specify: horizontal vertical -- One value used to specify: slice +# Returns -```text - border-image-slice: 3 3 4 3; -``` +the tabstops, or `None` if none was set. + +Retrieves the contents of the entry widget. +See also `Editable::get_chars`. -## border-image-width: [length|percentage]{1,4}; +This is equivalent to: -Defines the offset to use for dividing the border image in nine -parts, the top-left corner, central top edge, top-right-corner, -central right edge, bottom-right corner, central bottom edge, -bottom-left corner, and central right edge. They represent inward -distance from the top, right, bottom, and left edges. -- Four values used to specify: top right bottom left; -- Three values used to specify: top horizontal bottom -- Two values used to specify: vertical horizontal -- One value used to specify: width -```text - border-image-width: 4px 0 4px 0; +```C +GtkEntryBuffer *buffer; +buffer = gtk_entry_get_buffer (entry); +gtk_entry_buffer_get_text (buffer); ``` -## border-image-repeat: [none|url|linear-gradient]{1,4}; +# Returns -Defines how the middle part of a border image is handled to match -the size of the border. It has a one-value syntax which describes -the behavior for all sides, and a two-value syntax that sets a -different value for the horizontal and vertical behavior. -- Two values used to specify: horizontal vertical -- One value used to specify: repeat +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. + +Gets the area where the entry’s text is drawn. This function is +useful when drawing something to the entry in a draw callback. -```text - border-image-repeat: stretch; -``` +If the entry is not realized, `text_area` is filled with zeros. -## background-image: [none|url|linear-gradient], ... -Sets one or several background images for an element. The images -are drawn on successive stacking context layers, with the first -specified being drawn as if it is the closest to the user. The -borders of the element are then drawn on top of them, and the -background-color is drawn beneath them. -- There can be several sources listed, separated by commas. +See also `EntryExt::get_icon_area`. +## `text_area` +Return location for the text area. + +Retrieves the current length of the text in +`self`. -```text - background-image: gtk-gradient (linear, - left top, right top, - from (#fff), to (#000)); -``` +This is equivalent to: -## background-repeat: [repeat|no-repeat|space|round|repeat-x|repeat-y]; - -Defines how background images are repeated. A background image can -be repeated along the horizontal axis, the vertical axis, both, or -not repeated at all. -- `repeat`: The image is repeated in the given direction as much as - needed to cover the whole background image painting area. The - last image may be clipped if the whole thing won't fit in the - remaining area. -- `space`: The image is repeated in the given direction as much as - needed to cover most of the background image painting area, - without clipping an image. The remaining non-covered space is - spaced out evenly between the images. The first and last images - touches the edge of the element. The value of the - background-position CSS property is ignored for the concerned - direction, except if one single image is greater than the - background image painting area, which is the only case where an - image can be clipped when the space value is used. -- `round`: The image is repeated in the given direction as much as - needed to cover most of the background image painting area, - without clipping an image. If it doesn't cover exactly the area, - the tiles are resized in that direction in order to match it. -- `no-repeat`: The image is not repeated (and hence the background - image painting area will not necessarily been entirely - covered). The position of the non-repeated background image is - defined by the background-position CSS property. -- Note if not specified, the style doesn’t respect the CSS3 - specification, since the background will be stretched to fill - the area. -```text - background-repeat: no-repeat; +```C +GtkEntryBuffer *buffer; +buffer = gtk_entry_get_buffer (entry); +gtk_entry_buffer_get_length (buffer); ``` -## text-shadow: horizontal_offset vertical_offset [ blur_radius ] color; - -A shadow list can be applied to text or symbolic icons, using the CSS3 -text-shadow syntax, as defined in the -[CSS3 Specification](http://www.w3.org/TR/css3-text/`text`-shadow). +# Returns -- The offset of the shadow is specified with the -`horizontal_offset` and `vertical_offset` parameters. -- The optional blur radius is parsed, but it is currently not -rendered by the GTK+ theming engine. +the current number of characters + in `Entry`, or 0 if there are none. + +Retrieves whether the text in `self` is visible. See +`EntryExt::set_visibility`. -To set a shadow on an icon, use the `icon-shadow` property instead, -with the same syntax. +# Returns -To set multiple shadows on an element, you can specify a comma-separated list -of shadow elements in the `text-shadow` or `icon-shadow` property. Shadows are -always rendered front to back (i.e. the first shadow specified is on top of the -others). Shadows can thus overlay each other, but they can never overlay the -text or icon itself, which is always rendered on top of the shadow layer. +`true` if the text is currently visible + +Gets the value set by `EntryExt::set_width_chars`. +# Returns -```text - text-shadow: 1 1 0 blue, -4 -4 red; -``` +number of chars to request space for, or negative if unset + +Causes `self` to have keyboard focus. -## box-shadow: [ inset ] horizontal_offset vertical_offset [ blur_radius ] [ spread ] color; +It behaves like `WidgetExt::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. -Themes can apply shadows on framed elements using the CSS3 box-shadow syntax, -as defined in the -[CSS3 Specification](http://www.w3.org/TR/css3-background/`the`-box-shadow). +Feature: `v3_16` -- A positive offset will draw a shadow that is offset to the right (down) of the box, -- A negative offset to the left (top). -- The optional spread parameter defines an additional distance to -expand the shadow shape in all directions, by the specified radius. -- The optional blur radius parameter is parsed, but it is currently not rendered by -the GTK+ theming engine. -- The inset parameter defines whether the drop shadow should be rendered inside or outside -the box canvas. + +Allow the `Entry` 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 +`IMContextExt::filter_keypress`. -To set multiple box-shadows on an element, you can specify a comma-separated list -of shadow elements in the `box-shadow` property. Shadows are always rendered -front to back (i.e. the first shadow specified is on top of the others) so they may -overlap other boxes or other shadows. +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 `Entry`. +See `TextViewExt::reset_im_context` for an example of use. +## `event` +the key event +# Returns -```text - box-shadow: inset 0 1px 1px alpha(black, 0.1); -``` +`true` if the input method handled the key event. + +Converts from a position in the entry contents (returned +by `EntryExt::get_text`) to a position in the +entry’s `pango::Layout` (returned by `EntryExt::get_layout`, +with text retrieved via `pango::LayoutExt::get_text`). +## `layout_index` +byte index into the entry layout text -## transition: duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]; +# Returns -Styles can specify transitions that will be used to create a -gradual change in the appearance when a widget state changes. -- The `duration` is the amount of time that the animation will take -for a complete cycle from start to end. -- If the loop option is given, the animation will be repated until -the state changes again. -- The option after the duration determines the transition function -from a small set of predefined functions. +byte index into the entry contents + +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 +`EntryExt::progress_pulse` causes the block to move by a little bit +(the amount of movement per pulse is determined by +`EntryExt::set_progress_pulse_step`). + +Reset the input method context of the entry if needed. -- Linear +This can be necessary in the case where modifying the buffer +would confuse on-going input method behavior. + +If `setting` is `true`, pressing Enter in the `self` 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. - ![](linear.png) +(For experts: if `setting` is `true`, the entry calls +`WindowExt::activate_default` on the window containing the entry, in +the default handler for the `Entry::activate` signal.) +## `setting` +`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. +## `xalign` +The horizontal alignment, from 0 (left) to 1 (right). + Reversed for RTL layouts + +Sets a `pango::AttrList`; the attributes in the list are applied to the +entry text. -- Ease transition +Feature: `v3_6` -![](ease.png) +## `attrs` +a `pango::AttrList` + +Set the `EntryBuffer` object which holds the text for +this widget. +## `buffer` +a `EntryBuffer` + +Sets `completion` to be the auxiliary completion object to use with `self`. +All further configuration of the completion mechanism is done on +`completion` using the `EntryCompletion` API. Completion is disabled if +`completion` is set to `None`. +## `completion` +The `EntryCompletion` or `None` + +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 `ScrolledWindowExt::get_hadjustment` for a typical way of obtaining +the adjustment. -- Ease-in-out transition +The adjustment has to be in pixel units and in the same coordinate system +as the entry. +## `adjustment` +an adjustment which should be adjusted when the cursor + is moved, or `None` + +Sets whether the entry has a beveled frame around it. +## `setting` +new value + +Sets whether the icon is activatable. +## `icon_pos` +Icon position +## `activatable` +`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. -![](ease-in-out.png) +To handle the drag operation, you need to connect to the usual +`Widget::drag-data-get` (or possibly `Widget::drag-data-delete`) +signal, and use `EntryExt::get_current_icon_drag_source` in +your signal handler to find out if the drag was started from +an icon. -- Ease-in transition +By default, GTK+ uses the icon as the drag icon. You can use the +`Widget::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. +## `icon_pos` +icon position +## `target_list` +the targets (data formats) in which the data can be provided +## `actions` +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. -![](ease-in.png) +If `icon` is `None`, no icon will be shown in the specified position. +## `icon_pos` +The position at which to set the icon +## `icon` +The icon to set, or `None` + +Sets the icon shown in the entry at the specified position +from the current icon theme. -- Ease-out transition +If the icon name isn’t known, a “broken image” icon will be displayed +instead. -![](ease-out.png) +If `icon_name` is `None`, no icon will be shown in the specified position. +## `icon_pos` +The position at which to set the icon +## `icon_name` +An icon name, or `None` + +Sets the icon shown in the specified position using a pixbuf. +If `pixbuf` is `None`, no icon will be shown in the specified position. +## `icon_pos` +Icon position +## `pixbuf` +A `gdk_pixbuf::Pixbuf`, or `None` + +Sets the icon shown in the entry at the specified position from +a stock image. -```text - transition: 150ms ease-in-out; -``` +If `stock_id` is `None`, no icon will be shown in the specified position. +# Deprecated since 3.10 -## gtk-key-bindings: binding1, binding2, ...; +Use `EntryExt::set_icon_from_icon_name` instead. +## `icon_pos` +Icon position +## `stock_id` +The name of the stock item, or `None` + +Sets the sensitivity for the specified icon. +## `icon_pos` +Icon position +## `sensitive` +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]. -Key binding set name list. +Use `None` for `tooltip` to remove an existing tooltip. -## Other Properties +See also `WidgetExt::set_tooltip_markup` and +`EntryExt::set_icon_tooltip_text`. +## `icon_pos` +the icon position +## `tooltip` +the contents of the tooltip for the icon, or `None` + +Sets `tooltip` as the contents of the tooltip for the icon +at the specified position. -`GtkThemingEngines` can register their own, engine-specific style properties -with the function `ThemingEngine::register_property`. These properties -can be set in CSS like other properties, using a name of the form -`-namespace-name`, where namespace is typically -the name of the theming engine, and name is the -name of the property. Style properties that have been registered by widgets -using `WidgetClass::install_style_property` can also be set in this -way, using the widget class name for namespace. +Use `None` for `tooltip` to remove an existing tooltip. -An example for using engine-specific style properties: +See also `WidgetExt::set_tooltip_text` and +`EntryExt::set_icon_tooltip_markup`. +## `icon_pos` +the icon position +## `tooltip` +the contents of the tooltip for the icon, or `None` + +Sets `entry`’s inner-border property to `border`, or clears it if `None` +is passed. The inner-border is the area around the entry’s text, but +inside its frame. -```text -* { - engine: clearlooks; - border-radius: 4; - -GtkPaned-handle-size: 6; - -clearlooks-colorize-scrollbar: false; -} -``` +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. -# Implements +# Deprecated since 3.4 -[`ObjectExt`](trait.ObjectExt.html), [`StyleProviderExt`](trait.StyleProviderExt.html) - -Returns a newly created `CssProvider`. +Use the standard border and padding CSS properties (through + objects like `StyleContext` and `CssProvider`); the value set with + this function is ignored by `Entry`. +## `border` +a `Border`, or `None` + +Sets the `Entry:input-hints` property, which +allows input methods to fine-tune their behaviour. -# Returns +Feature: `v3_6` -A new `CssProvider` - -Returns the provider containing the style settings used as a -fallback for all widgets. +## `hints` +the hints + +Sets the `Entry:input-purpose` property which +can be used by on-screen keyboards and other input +methods to adjust their behaviour. -# Returns +Feature: `v3_6` -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 -## `name` -A theme name -## `variant` -variant to load, for example, "dark", or - `None` for the default - -# Returns +## `purpose` +the purpose + +Sets the character to use in place of the actual text when +`EntryExt::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. +## `ch` +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. -a `CssProvider` with the theme loaded. - This memory is owned by GTK+, and you must not free it. - -Loads `data` into `self`, making it clear any previously loaded -information. -## `data` -CSS data loaded in memory -## `length` -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. +This is equivalent to: -# Returns -`true`. The return value is deprecated and `false` will only be - returned for backwards compatibility reasons if an `error` is not - `None` and a loading error occured. To track errors while loading - CSS, connect to the `CssProvider::parsing-error` signal. - -Loads the data contained in `file` into `self`, making it -clear any previously loaded information. -## `file` -`gio::File` pointing to a file to load +```C +GtkEntryBuffer *buffer; +buffer = gtk_entry_get_buffer (entry); +gtk_entry_buffer_set_max_length (buffer, max); +``` +## `max` +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 `self`. -# Returns +Feature: `v3_12` -`true`. The return value is deprecated and `false` will only be - returned for backwards compatibility reasons if an `error` is not - `None` and a loading error occured. To track errors while loading - CSS, connect to the `CssProvider::parsing-error` signal. - -Loads the data contained in `path` into `self`, making it clear -any previously loaded information. -## `path` -the path of a filename to load, in the GLib filename encoding +## `n_chars` +the new desired maximum width, in characters + +Sets whether the text is overwritten when typing in the `Entry`. +## `overwrite` +new value + +Sets text to be displayed in `self` when it is empty and unfocused. +This can be used to give a visual hint of the expected contents of +the `Entry`. -# Returns +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. +## `text` +a string to be displayed when `self` is empty and unfocused, or `None` + +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. +## `fraction` +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 `EntryExt::progress_pulse`. +## `fraction` +fraction between 0.0 and 1.0 + +Sets a `pango::TabArray`; the tabstops in the array are applied to the entry +text. -`true`. The return value is deprecated and `false` will only be - returned for backwards compatibility reasons if an `error` is not - `None` and a loading error occured. To track errors while loading - CSS, connect to the `CssProvider::parsing-error` signal. - -Loads the data contained in the resource at `resource_path` into -the `CssProvider`, clearing any previously loaded information. +Feature: `v3_10` -To track errors while loading CSS, connect to the -`CssProvider::parsing-error` signal. +## `tabs` +a `pango::TabArray` + +Sets the text in the widget to the given +value, replacing the current contents. -Feature: `v3_16` +See `EntryBufferExt::set_text`. +## `text` +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. -## `resource_path` -a `gio::Resource` resource path - -Converts the `self` into a string representation in CSS -format. +By default, GTK+ picks the best invisible character available +in the current font, but it can be changed with +`EntryExt::set_invisible_char`. -Using `CssProvider::load_from_data` with the return value -from this function on a new provider created with -`CssProvider::new` will basically create a duplicate of -this `self`. +Note that you probably want to set `Entry:input-purpose` +to `InputPurpose::Password` or `InputPurpose::Pin` to +inform input methods about the purpose of this entry, +in addition to setting visibility to `false`. +## `visible` +`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. +## `n_chars` +width in chars + +Converts from a position in the entry’s `pango::Layout` (returned by +`EntryExt::get_layout`) to a position in the entry contents +(returned by `EntryExt::get_text`). +## `text_index` +byte index into the entry contents # Returns -a new string representing the `self`. - -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 `CssSection::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 -`self` is not yet parsed completely. This will for example -happen in the `CssProvider`::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. - -# Returns +byte index into the entry layout text + +Unsets the invisible char previously set with +`EntryExt::set_invisible_char`. So that the +default invisible char is used again. + +The `EntryBuffer` class contains the actual text displayed in a +`Entry` widget. -the line number - -Returns the offset in bytes from the start of the current line -returned via `CssSection::get_end_line`. -This value may change in future invocations of this function if -`self` is not yet parsed completely. This will for example -happen in the `CssProvider`::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. +A single `EntryBuffer` object can be shared by multiple `Entry` +widgets which will then share the same text content, but not the cursor +position, visibility attributes, icon etc. -# Returns +`EntryBuffer` 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. -the offset in bytes from the start of the line. - -Gets the file that `self` was parsed from. If no such file exists, -for example because the CSS was loaded via -`CssProvider::load_from_data`(), then `None` is returned. +# Implements -# Returns +[`EntryBufferExt`](trait.EntryBufferExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `EntryBuffer` methods. -the `gio::File` that `self` was parsed from - or `None` if `self` was parsed from other data - -Gets the parent section for the given `self`. The parent section is -the section that contains this `self`. A special case are sections of -type `CssSectionType::Document`. Their parent will either be `None` -if they are the original CSS document that was loaded by -`CssProvider::load_from_file` or a section of type -`CssSectionType::Import` if it was loaded with an import rule from -a different file. +# Implementors -# Returns +[`EntryBuffer`](struct.EntryBuffer.html) + +Create a new `EntryBuffer` object. -the parent section or `None` if none - -Gets the type of information that `self` describes. +Optionally, specify initial text to set in the buffer. +## `initial_chars` +initial buffer text, or `None` +## `n_initial_chars` +number of characters in `initial_chars`, or -1 # Returns -the type of `self` - -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. +A new `EntryBuffer` object. + +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. -# Returns +If `position` or `n_chars` are out of bounds, then they are coerced to sane +values. -the line number - -Returns the offset in bytes from the start of the current line -returned via `CssSection::get_start_line`. +Note that the positions are specified in characters, not bytes. +## `position` +position at which to delete text +## `n_chars` +number of characters to delete # Returns -the offset in bytes from the start of the line. - -Increments the reference count on `self`. +The number of characters deleted. + +Used when subclassing `EntryBuffer` +## `position` +position at which text was deleted +## `n_chars` +number of characters deleted + +Used when subclassing `EntryBuffer` +## `position` +position at which text was inserted +## `chars` +text that was inserted +## `n_chars` +number of characters inserted + +Retrieves the length in bytes of the buffer. +See `EntryBufferExt::get_length`. # Returns -`self` itself. - -Decrements the reference count on `self`, freeing the -structure if the reference count reaches 0. - -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 `CssSection::get_parent` - might return `None`. - -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: `Entry::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. - -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 -`VBox`, and is where widgets such as a `Label` or a `Entry` 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. - -`Dialog` boxes are created with a call to `Dialog::new` or -`Dialog::new_with_buttons`. `Dialog::new_with_buttons` is -recommended; it allows you to set the dialog title, some convenient -flags, and add simple buttons. +The byte length of the buffer. + +Retrieves the length in characters of the buffer. -If “dialog” is a newly created dialog, the two primary areas of the -window can be accessed through `DialogExt::get_content_area` and -`DialogExt::get_action_area`, as can be seen from the example below. +# Returns -A “modal” dialog (that is, one which freezes the rest of the application -from user input), can be created by calling `Window::set_modal` on the -dialog. Use the GTK_WINDOW() macro to cast the widget returned from -`Dialog::new` into a `Window`. When using `Dialog::new_with_buttons` -you can also pass the `DialogFlags::Modal` flag to make a dialog modal. +The number of characters in the buffer. + +Retrieves the maximum allowed length of the text in +`self`. See `EntryBufferExt::set_max_length`. -If you add buttons to `Dialog` using `Dialog::new_with_buttons`, -`DialogExt::add_button`, `DialogExt::add_buttons`, or -`DialogExt::add_action_widget`, clicking the button will emit a signal -called `Dialog::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 -`ResponseType` enumeration (these all have values less than zero). If -a dialog receives a delete event, the `Dialog::response` signal will -be emitted with a response ID of `ResponseType::DeleteEvent`. +# Returns -If you want to block waiting for a dialog to return before returning -control flow to your code, you can call `DialogExt::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. +the maximum allowed number of characters + in `EntryBuffer`, or 0 if there is no maximum. + +Retrieves the contents of the buffer. -For the simple dialog in the following example, in reality you’d probably -use `MessageDialog` 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. +The memory pointer returned by this call will not change +unless this object emits a signal, or is finalized. -An example for simple `Dialog` usage: +# Returns -```C -// Function to open a dialog box with a message -void -quick_message (GtkWindow *parent, gchar *message) -{ - GtkWidget *dialog, *label, *content_area; - GtkDialogFlags flags; +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. + +Inserts `n_chars` characters of `chars` into the contents of the +buffer, at position `position`. - // 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); +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. - // Ensure that the dialog box is destroyed when the user responds +Note that the position and length are in characters, not in bytes. +## `position` +the position at which to insert text. +## `chars` +the text to insert into the buffer. +## `n_chars` +the length of the text in characters, or -1 - g_signal_connect_swapped (dialog, - "response", - G_CALLBACK (gtk_widget_destroy), - dialog); +# Returns - // Add the label, and show everything we’ve added +The number of characters actually inserted. + +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. +## `max_length` +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. - gtk_container_add (GTK_CONTAINER (content_area), label); - gtk_widget_show_all (dialog); -} -``` +This is roughly equivalent to calling `EntryBufferExt::delete_text` +and `EntryBufferExt::insert_text`. -# `Dialog` as `Buildable` +Note that `n_chars` is in characters, not in bytes. +## `chars` +the new text +## `n_chars` +the number of characters in `text`, or -1 + +`EntryCompletion` is an auxiliary object to be used in conjunction with +`Entry` to provide the completion functionality. It implements the +`CellLayout` interface, to allow the user to add extra cells to the +`TreeView` with completion matches. -The `Dialog` implementation of the `Buildable` interface exposes the -`vbox` and `action_area` as internal children with the names “vbox” and -“action_area”. +“Completion functionality” means that when the user modifies the text +in the entry, `EntryCompletion` 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 +`EntryCompletionExt::set_text_column`), but this can be overridden +with a custom match function (see `EntryCompletionExt::set_match_func`). -`Dialog` supports a custom `` element, which can contain -multiple `` 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 `` element -to true. +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 `EntryCompletion::match-selected` signal and updating the +entry in the signal handler. Note that you should return `true` from +the signal handler to suppress the default behaviour. -`Dialog` supports adding action widgets by specifying “action“ as -the “type“ attribute of a `` 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 `` element. +To add completion functionality to an entry, use `EntryExt::set_completion`. -An example of a `Dialog` UI definition fragment: +In addition to regular completion matches, which will be inserted into the +entry when they are selected, `EntryCompletion` 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 `EntryCompletion::action-activated` signal is emitted. -```text - - - - - - - True - - - - button_cancel - button_ok - - -``` +`EntryCompletion` uses a `TreeModelFilter` model to represent the +subset of the entire model that is currently matching. While the +`EntryCompletion` signals `EntryCompletion::match-selected` and +`EntryCompletion::cursor-on-match` take the original model and an +iter pointing to that model as arguments, other callbacks and signals +(such as ``GtkCellLayoutDataFuncs`` or `CellArea::apply-attributes`) +will generally take the filter model as argument. As long as you are +only calling `TreeModel::get`, this will make no difference to +you. If for some reason, you need the original model, use +`TreeModelFilterExt::get_model`. Don’t forget to use +`TreeModelFilterExt::convert_iter_to_child_iter` to obtain a +matching iter. # Implements -[`DialogExt`](trait.DialogExt.html), [`WindowExt`](trait.WindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) - -Trait containing all `Dialog` methods. +[`EntryCompletionExt`](trait.EntryCompletionExt.html), [`ObjectExt`](trait.ObjectExt.html), [`CellLayoutExt`](trait.CellLayoutExt.html) + +Trait containing all `EntryCompletion` methods. # Implementors -[`AboutDialog`](struct.AboutDialog.html), [`AppChooserDialog`](struct.AppChooserDialog.html), [`ColorChooserDialog`](struct.ColorChooserDialog.html), [`Dialog`](struct.Dialog.html), [`FileChooserDialog`](struct.FileChooserDialog.html), [`FontChooserDialog`](struct.FontChooserDialog.html), [`MessageDialog`](struct.MessageDialog.html), [`RecentChooserDialog`](struct.RecentChooserDialog.html) - -Creates a new dialog box. - -Widgets should not be packed into this `Window` -directly, but into the `vbox` and `action_area`, as described above. +[`EntryCompletion`](struct.EntryCompletion.html) + +Creates a new `EntryCompletion` object. # Returns -the new dialog as a `Widget` - -Creates a new `Dialog` with title `title` (or `None` for the default -title; see `Window::set_title`) and transient parent `parent` (or -`None` for none; see `Window::set_transient_for`). The `flags` -argument can be used to make the dialog modal (`DialogFlags::Modal`) -and/or to have it destroyed along with its transient parent -(`DialogFlags::DestroyWithParent`). After `flags`, button -text/response ID pairs should be listed, with a `None` 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 `ResponseType` -enumeration. If the user clicks one of these dialog buttons, -`Dialog` will emit the `Dialog::response` signal with the corresponding -response ID. If a `Dialog` receives the `Widget::delete-event` signal, -it will emit ::response with a response ID of `ResponseType::DeleteEvent`. -However, destroying a dialog does not emit the ::response signal; -so be careful relying on ::response when using the -`DialogFlags::DestroyWithParent` 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: - -```C - 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); -``` -## `title` -Title of the dialog, or `None` -## `parent` -Transient parent of the dialog, or `None` -## `flags` -from `DialogFlags` -## `first_button_text` -text to go in first button, or `None` +A newly created `EntryCompletion` object + +Creates a new `EntryCompletion` object using the +specified `area` to layout cells in the underlying +`TreeViewColumn` for the drop-down menu. +## `area` +the `CellArea` used to layout cells # Returns -a new `Dialog` - -Adds an activatable widget to the action area of a `Dialog`, -connecting a signal handler that will emit the `Dialog::response` -signal on the dialog when the widget is activated. The widget is -appended to the end of the dialog’s action area. If you want to add a -non-activatable widget, simply pack it into the `action_area` field -of the `Dialog` struct. -## `child` -an activatable widget -## `response_id` -response ID for `child` - -Adds a button with the given text and sets things up so that -clicking the button will emit the `Dialog::response` signal with -the given `response_id`. The button is appended to the end of the -dialog’s action area. The button widget is returned, but usually -you don’t need it. -## `button_text` -text of button -## `response_id` -response ID for the button +A newly created `EntryCompletion` object + +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. + +Computes the common prefix that is shared by all rows in `self` +that start with `key`. If no row matches `key`, `None` will be returned. +Note that a text column must have been set for this function to work, +see `EntryCompletionExt::set_text_column` for details. +## `key` +The text to complete for # Returns -the `Button` widget that was added - -Adds more buttons, same as calling `DialogExt::add_button` -repeatedly. The variable argument list should be `None`-terminated -as with `Dialog::new_with_buttons`. Each button must have both -text and response ID. -## `first_button_text` -button text - -Returns the action area of `self`. - -# Deprecated since 3.12 +The common prefix all rows starting with + `key` or `None` if no row matches `key`. + +Deletes the action at `index_` from `self`’s action list. -Direct access to the action area - is discouraged; use `DialogExt::add_button`, etc. +Note that `index_` is a relative position and the position of an +action may have changed since it was inserted. +## `index_` +the index of the item to delete + +Get the original text entered by the user that triggered +the completion or `None` if there’s no completion ongoing. # Returns -the action area - -Returns the content area of `self`. +the prefix for the current completion + +Gets the entry `self` has been attached to. # Returns -the content area `Box`. - -Returns the header bar of `self`. Note that the -headerbar is only used by the dialog if the -`Dialog:use-header-bar` property is `true`. +The entry `self` has been attached to + +Returns whether the common prefix of the possible completions should +be automatically inserted in the entry. -Feature: `v3_12` +# Returns +`true` if inline completion is turned on + +Returns `true` if inline-selection mode is turned on. # Returns -the header bar - -Gets the response id of a widget in the action area -of a dialog. -## `widget` -a widget in the action area of `self` +`true` if inline-selection mode is on + +Returns the minimum key length as set for `self`. # Returns -the response id of `widget`, or `ResponseType::None` - if `widget` doesn’t have a response id set. - -Gets the widget button that uses the given response ID in the action area -of a dialog. -## `response_id` -the response ID used by the `self` widget +The currently used minimum key length + +Returns the model the `EntryCompletion` is using as data source. +Returns `None` if the model is unset. # Returns -the `widget` button that uses the given - `response_id`, or `None`. - -Emits the `Dialog::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 `DialogExt::run` will be monitoring the -::response signal and take appropriate action. -## `response_id` -response ID - -Blocks in a recursive main loop until the `self` either emits the -`Dialog::response` signal, or is destroyed. If the dialog is -destroyed during the call to `DialogExt::run`, `DialogExt::run` returns -`ResponseType::None`. Otherwise, it returns the response ID from the -::response signal emission. +A `TreeModel`, or `None` if none + is currently being used + +Returns whether the completions should be presented in a popup window. -Before entering the recursive main loop, `DialogExt::run` calls -`Widget::show` on the dialog for you. Note that you still -need to show any children of the dialog yourself. +# Returns -During `DialogExt::run`, the default behavior of `Widget::delete-event` -is disabled; if the dialog receives ::delete_event, it will not be -destroyed as windows usually are, and `DialogExt::run` will return -`ResponseType::DeleteEvent`. Also, during `DialogExt::run` the dialog -will be modal. You can force `DialogExt::run` to return at any time by -calling `DialogExt::response` to emit the ::response signal. Destroying -the dialog during `DialogExt::run` is a very bad idea, because your -post-run code won’t know whether the dialog was destroyed or not. +`true` if popup completion is turned on + +Returns whether the completion popup window will be resized to the +width of the entry. -After `DialogExt::run` returns, you are responsible for hiding or -destroying the dialog if you wish to do so. +# Returns -Typical usage of this function might be: +`true` if the popup window will be resized to the width of + the entry + +Returns whether the completion popup window will appear even if there is +only a single match. -```C - gint 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); -``` +# Returns -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 `DialogExt::run` call. +`true` if the popup window will appear regardless of the + number of matches + +Returns the column in the model of `self` to get strings from. # Returns -response ID - -Sets an alternative button order. If the -`Settings: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. +the column containing the strings + +Inserts an action in `self`’s action item list at position `index_` +with markup `markup`. +## `index_` +the index of the item to insert +## `markup` +markup of the item to insert + +Inserts an action in `self`’s action item list at position `index_` +with text `text`. If you want the action item to have markup, use +`EntryCompletionExt::insert_action_markup`. -Use this function after adding all the buttons to your dialog, as the -following example shows: +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. +## `index_` +the index of the item to insert +## `text` +text of the item to insert + +Requests a prefix insertion. + +Sets whether the common prefix of the possible completions should +be automatically inserted in the entry. +## `inline_completion` +`true` to do inline completion + +Sets whether it is possible to cycle through the possible completions +inside the entry. +## `inline_selection` +`true` to do inline selection + +Sets the match function for `self` to be `func`. The match function +is used to determine if a row should or should not be in the completion +list. +## `func` +the ``GtkEntryCompletionMatchFunc`` to use +## `func_data` +user data for `func` +## `func_notify` +destroy notify for `func_data`. + +Requires the length of the search key for `self` 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). +## `length` +the minimum length of the key in order to start completing + +Sets the model for a `EntryCompletion`. If `self` already has +a model set, it will remove it before setting the new model. +If model is `None`, then it will unset the model. +## `model` +the `TreeModel` + +Sets whether the completions should be presented in a popup window. +## `popup_completion` +`true` to do popup completion + +Sets whether the completion popup window will be resized to be the same +width as the entry. +## `popup_set_width` +`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][`EntryCompletion`--inline-completion]. +## `popup_single_match` +`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 `self` +to have a list displaying all (and just) strings in the completion list, +and to get those strings from `column` in the model of `self`. +This functions creates and adds a `CellRendererText` for the selected +column. If you need to set the text column, but don't want the cell +renderer, use `gobject::ObjectExt::set` to set the `EntryCompletion:text-column` +property directly. +## `column` +the column in the model of `self` to get strings from + +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 `EventBox` widget is a subclass of `Bin` 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. -```C -cancel_button = gtk_dialog_add_button (GTK_DIALOG (dialog), - _("_Cancel"), - GTK_RESPONSE_CANCEL); +# Implements -ok_button = gtk_dialog_add_button (GTK_DIALOG (dialog), - _("_OK"), - GTK_RESPONSE_OK); +[`EventBoxExt`](trait.EventBoxExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `EventBox` methods. -gtk_widget_grab_default (ok_button); +# Implementors -help_button = gtk_dialog_add_button (GTK_DIALOG (dialog), - _("_Help"), - GTK_RESPONSE_HELP); +[`EventBox`](struct.EventBox.html) + +Creates a new `EventBox`. -gtk_dialog_set_alternative_button_order (GTK_DIALOG (dialog), - GTK_RESPONSE_OK, - GTK_RESPONSE_CANCEL, - GTK_RESPONSE_HELP, - -1); -``` +# Returns -# Deprecated since 3.10 +a new `EventBox` + +Returns whether the event box window is above or below the +windows of its child. See `EventBoxExt::set_above_child` +for details. -Deprecated -## `first_response_id` -a response id used by one `self`’s buttons - -Sets an alternative button order. If the -`Settings: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`. +# Returns -See `DialogExt::set_alternative_button_order` for more information. +`true` if the event box window is above the + window of its child + +Returns whether the event box has a visible window. +See `EventBoxExt::set_visible_window` for details. -This function is for use by language bindings. +# Returns -# Deprecated since 3.10 +`true` if the event box window is visible + +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. -Deprecated -## `n_params` -the number of response ids in `new_order` -## `new_order` -an array of response ids of - `self`’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. -## `response_id` -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. -## `response_id` -a response ID -## `setting` -`true` for sensitive - -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 -`Widget::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 `DrawingArea` 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 default is to keep the window below the child. +## `above_child` +`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. -- Mouse and button press signals to respond to input from - the user. (Use `Widget::add_events` to enable events - you wish to receive.) +In an invisible window event box, the window that the +event box creates is a `gdk::WindowWindowClass::InputOnly` window, which +means that it is invisible and only serves to receive +events. -- The `Widget::realize` signal to take any necessary actions - when the widget is instantiated on a particular display. - (Create GDK resources in response to this signal.) +A visible window event box creates a visible (`gdk::WindowWindowClass::InputOutput`) +window that acts as the parent window for all the widgets +contained in the event box. -- The `Widget::size-allocate` signal to take any necessary - actions when the widget changes size. +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 `Widget::draw` signal to handle redrawing the - contents of the widget. +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. -The following code portion demonstrates using a drawing -area to display a circle in the normal widget foreground -color. +There is one unexpected issue for an invisible event box that has its +window below the child. (See `EventBoxExt::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 `WidgetExt::add_events`), +it won’t be received by the event box. -Note that GDK automatically clears the exposed area to the -background color before sending the expose event, and that -drawing is implicitly clipped to the exposed area. +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. +## `visible_window` +`true` to make the event box have a visible window + +`EventController` 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. -## Simple `DrawingArea` usage +Feature: `v3_14` +# Implements -```C -gboolean -draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data) -{ - guint width, height; - GdkRGBA color; +[`EventControllerExt`](trait.EventControllerExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `EventController` methods. - width = gtk_widget_get_allocated_width (widget); - height = gtk_widget_get_allocated_height (widget); - cairo_arc (cr, - width / 2.0, height / 2.0, - MIN (width, height) / 2.0, - 0, 2 * G_PI); +Feature: `v3_14` - gtk_style_context_get_color (gtk_widget_get_style_context (widget), - 0, - &color); - gdk_cairo_set_source_rgba (cr, &color); +# Implementors - cairo_fill (cr); +[`EventController`](struct.EventController.html), [`Gesture`](struct.Gesture.html) + +Gets the propagation phase at which `self` handles events. - 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); -``` +Feature: `v3_14` -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; `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. +# Returns -To receive mouse events on a drawing area, you will need to enable -them with `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 `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. +the propagation phase + +Returns the `Widget` this controller relates to. -# Implements +Feature: `v3_14` -[`WidgetExt`](trait.WidgetExt.html), [`ObjectExt`](trait.ObjectExt.html) - -Creates a new drawing area. # Returns -a new `DrawingArea` - -The `Editable` interface is an interface which should be implemented by -text editing widgets, such as `Entry` and `SpinButton`. It contains functions -for generically manipulating an editable widget, a large number of action -signals used for key bindings, and several signals that an application can -connect to to modify the behavior of a widget. - -As an example of the latter usage, by connecting -the following handler to `Editable::insert-text`, an application -can convert all entry into a widget into uppercase. +a `Widget` + +Feeds an events into `self`, so it can be interpreted +and the controller actions triggered. -## Forcing entry to uppercase. +Feature: `v3_14` +## `event` +a ``GdkEvent`` -```C -#include ; +# Returns -void -insert_text_handler (GtkEditable *editable, - const gchar *text, - gint length, - gint *position, - gpointer data) -{ - gchar *result = g_utf8_strup (text, length); +`true` if the event was potentially useful to trigger the + controller action + +Resets the `self` to a clean state. Every interaction +the controller did through `EventController::handle-event` +will be dropped at this point. - 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); +Feature: `v3_14` - g_signal_stop_emission_by_name (editable, "insert_text"); + +Sets the propagation phase at which a controller handles events. - g_free (result); +If `phase` is `PropagationPhase::None`, no automatic event handling will be +performed, but other additional gesture maintenance will. In that phase, +the events can be managed by calling `EventControllerExt::handle_event`. + +Feature: `v3_14` + +## `phase` +a propagation phase + +Describes the state of a `gdk::EventSequence` in a `Gesture`. + +The sequence is handled, but not grabbed. + +The sequence is handled and grabbed. + +The sequence is denied. + +Feature: `v3_14` + + +A `Expander` allows the user to hide or show its child by clicking +on an expander triangle similar to the triangles used in a `TreeView`. + +Normally you use an expander as you would use any other descendant +of `Bin`; you create the child widget and use `ContainerExt::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 `Expander` +but do not add a child to it. The expander widget has an +`Expander:expanded` property which can be used to monitor +its expansion state. You should watch this property with a signal +connection as follows: + + +```C +expander = gtk_expander_new_with_mnemonic ("_More Options"); +g_signal_connect (expander, "notify::expanded", + G_CALLBACK (expander_callback), NULL); + +... + +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 + } } ``` +# `Expander` as `Buildable` + +The `Expander` implementation of the `Buildable` interface supports +placing a child in the label position by specifying “label” as the +“type” attribute of a `` element. A normal content child can be +specified without specifying a `` type attribute. + +An example of a UI definition fragment with `Expander`: + +```plain +expander +├── title +│ ├── arrow +│ ╰──