From 4bdbddcad1aa7e7a600cfbb96089d61877468eda Mon Sep 17 00:00:00 2001 From: Evgenii Pashkin Date: Sat, 12 Aug 2017 11:26:29 +0300 Subject: [PATCH 1/2] Regen vendor docs --- .travis.yml | 2 +- gdk/vendor.md | 2427 +++- gtk/vendor.md | 20929 +++++++++++++++++------------ gtksource/{docs.md => vendor.md} | 239 +- src/lib.rs | 2 +- 5 files changed, 14578 insertions(+), 9021 deletions(-) rename gtksource/{docs.md => vendor.md} (98%) 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/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 +│ ╰──