gtk-rs-lgpl-docs-0.1.12/.gitignore010064400007650000024000000000221344544735200151000ustar0000000000000000target Cargo.lock gtk-rs-lgpl-docs-0.1.12/.travis.yml010064400007650000024000000006161344544735200152320ustar0000000000000000dist: xenial language: rust rust: - nightly - beta - stable env: - GTK=3.14 FEATURES= - GTK=3.24 FEATURES=v3_16 addons: apt: packages: - libgtk-3-dev - libmount-dev script: - rustc --version - mkdir .cargo - echo 'paths = ["."]' > .cargo/config - git clone -q --depth 50 -b pending https://github.com/gtk-rs/examples _examples - cd _examples - ./build_travis.sh gtk-rs-lgpl-docs-0.1.12/atk/vendor.md010064400007650000024000004410441350423663000155120ustar0000000000000000 `Action` should be implemented by instances of `Object` classes with which the user can interact directly, i.e. buttons, checkboxes, scrollbars, e.g. components which are not "passive" providers of UI information. Exceptions: when the user interaction is already covered by another appropriate interface such as `EditableText` (insert/delete text, etc.) or `Value` (set value) then these actions should not be exposed by `Action` as well. Though most UI interactions on components should be invocable via keyboard as well as mouse, there will generally be a close mapping between "mouse actions" that are possible on a component and the AtkActions. Where mouse and keyboard actions are redundant in effect, `Action` should expose only one action rather than exposing redundant actions if possible. By convention we have been using "mouse centric" terminology for `Action` names. # Implements [`AtkActionExt`](trait.AtkActionExt.html) Trait containing all `Action` methods. # Implementors [`Action`](struct.Action.html), [`Hyperlink`](struct.Hyperlink.html), [`NoOpObject`](struct.NoOpObject.html) Perform the specified action on the object. ## `i` the action index corresponding to the action to be performed # Returns `true` if success, `false` otherwise Returns a description of the specified action of the object. ## `i` the action index corresponding to the action to be performed # Returns a description string, or `None` if `self` does not implement this interface. Gets the keybinding which can be used to activate this action, if one exists. The string returned should contain localized, human-readable, key sequences as they would appear when displayed on screen. It must be in the format "mnemonic;sequence;shortcut". - The mnemonic key activates the object if it is presently enabled onscreen. This typically corresponds to the underlined letter within the widget. Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for a button. - The sequence is the full list of keys which invoke the action even if the relevant element is not currently shown on screen. For instance, for a menu item the sequence is the keybindings used to open the parent menus before invoking. The sequence string is colon-delimited. Example: "Alt+F:N" in a traditional "New..." menu item. - The shortcut, if it exists, will invoke the same action without showing the component or its enclosing menus or dialogs. Example: "Ctrl+N" in a traditional "New..." menu item. Example: For a traditional "New..." menu item, the expected return value would be: "N;Alt+F:N;Ctrl+N" for the English locale and "N;Alt+D:N;Strg+N" for the German locale. If, hypothetically, this menu item lacked a mnemonic, it would be represented by ";;Ctrl+N" and ";;Strg+N" respectively. ## `i` the action index corresponding to the action to be performed # Returns the keybinding which can be used to activate this action, or `None` if there is no keybinding for this action. Returns the localized name of the specified action of the object. ## `i` the action index corresponding to the action to be performed # Returns a name string, or `None` if `self` does not implement this interface. Gets the number of accessible actions available on the object. If there are more than one, the first one is considered the "default" action of the object. # Returns a the number of actions, or 0 if `self` does not implement this interface. Returns a non-localized string naming the specified action of the object. This name is generally not descriptive of the end result of the action, but instead names the 'interaction type' which the object supports. By convention, the above strings should be used to represent the actions which correspond to the common point-and-click interaction techniques of the same name: i.e. "click", "press", "release", "drag", "drop", "popup", etc. The "popup" action should be used to pop up a context menu for the object, if one exists. For technical reasons, some toolkits cannot guarantee that the reported action is actually 'bound' to a nontrivial user event; i.e. the result of some actions via `Action::do_action` may be NIL. ## `i` the action index corresponding to the action to be performed # Returns a name string, or `None` if `self` does not implement this interface. Sets a description of the specified action of the object. ## `i` the action index corresponding to the action to be performed ## `desc` the description to be assigned to this action # Returns a gboolean representing if the description was successfully set; AtkAttribute is a string name/value pair representing a generic attribute. This can be used to expose additional information from an accessible object as a whole (see `AtkObjectExt::get_attributes`) or an document (see `Document::get_attributes`). In the case of text attributes (see `Text::get_default_attributes`), `TextAttribute` enum defines all the possible text attribute names. You can use `TextAttribute::get_name` to get the string name from the enum value. See also `TextAttribute::for_name` and `TextAttribute::get_value` for more information. A string name/value pair representing a generic attribute. Frees the memory used by an `AttributeSet`, including all its `AtkAttributes`. ## `attrib_set` The `AttributeSet` to free `Component` should be implemented by most if not all UI elements with an actual on-screen presence, i.e. components which can be said to have a screen-coordinate bounding box. Virtually all widgets will need to have `Component` implementations provided for their corresponding `Object` class. In short, only UI elements which are *not* GUI elements will omit this ATK interface. A possible exception might be textual information with a transparent background, in which case text glyph bounding box information is provided by `Text`. # Implements [`ComponentExt`](trait.ComponentExt.html) Trait containing all `Component` methods. # Implementors [`Component`](struct.Component.html), [`NoOpObject`](struct.NoOpObject.html), [`Plug`](struct.Plug.html), [`Socket`](struct.Socket.html) Checks whether the specified point is within the extent of the `self`. Toolkit implementor note: ATK provides a default implementation for this virtual method. In general there are little reason to re-implement it. ## `x` x coordinate ## `y` y coordinate ## `coord_type` specifies whether the coordinates are relative to the screen or to the components top level window # Returns `true` or `false` indicating whether the specified point is within the extent of the `self` or not Returns the alpha value (i.e. the opacity) for this `self`, on a scale from 0 (fully transparent) to 1.0 (fully opaque). # Returns An alpha value from 0 to 1.0, inclusive. Gets the rectangle which gives the extent of the `self`. ## `x` address of `gint` to put x coordinate ## `y` address of `gint` to put y coordinate ## `width` address of `gint` to put width ## `height` address of `gint` to put height ## `coord_type` specifies whether the coordinates are relative to the screen or to the components top level window Gets the layer of the component. # Returns an `Layer` which is the layer of the component Gets the zorder of the component. The value G_MININT will be returned if the layer of the component is not ATK_LAYER_MDI or ATK_LAYER_WINDOW. # Returns a gint which is the zorder of the component, i.e. the depth at which the component is shown in relation to other components in the same container. Gets the position of `self` in the form of a point specifying `self`'s top-left corner. # Deprecated Since 2.12. Use `Component::get_extents` instead. ## `x` address of `gint` to put x coordinate position ## `y` address of `gint` to put y coordinate position ## `coord_type` specifies whether the coordinates are relative to the screen or to the components top level window Gets the size of the `self` in terms of width and height. # Deprecated Since 2.12. Use `Component::get_extents` instead. ## `width` address of `gint` to put width of `self` ## `height` address of `gint` to put height of `self` Grabs focus for this `self`. # Returns `true` if successful, `false` otherwise. Gets a reference to the accessible child, if one exists, at the coordinate point specified by `x` and `y`. ## `x` x coordinate ## `y` y coordinate ## `coord_type` specifies whether the coordinates are relative to the screen or to the components top level window # Returns a reference to the accessible child, if one exists Makes `self` visible on the screen by scrolling all necessary parents. Contrary to atk_component_set_position, this does not actually move `self` in its parent, this only makes the parents scroll so that the object shows up on the screen, given its current position within the parents. Feature: `v2_30` ## `type_` specify where the object should be made visible. # Returns whether scrolling was successful. Makes an object visible on the screen at a given position by scrolling all necessary parents. Feature: `v2_30` ## `coords` specify whether coordinates are relative to the screen or to the parent object. ## `x` x-position where to scroll to ## `y` y-position where to scroll to # Returns whether scrolling was successful. Sets the extents of `self`. ## `x` x coordinate ## `y` y coordinate ## `width` width to set for `self` ## `height` height to set for `self` ## `coord_type` specifies whether the coordinates are relative to the screen or to the components top level window # Returns `true` or `false` whether the extents were set or not Sets the position of `self`. Contrary to atk_component_scroll_to, this does not trigger any scrolling, this just moves `self` in its parent. ## `x` x coordinate ## `y` y coordinate ## `coord_type` specifies whether the coordinates are relative to the screen or to the component's top level window # Returns `true` or `false` whether or not the position was set or not Set the size of the `self` in terms of width and height. ## `width` width to set for `self` ## `height` height to set for `self` # Returns `true` or `false` whether the size was set or not The 'bounds-changed" signal is emitted when the bposition or size of the component changes. ## `arg1` The AtkRectangle giving the new position and size. Specifies how xy coordinates are to be interpreted. Used by functions such as `Component::get_position` and `Text::get_character_extents` specifies xy coordinates relative to the screen specifies xy coordinates relative to the widget's top-level window specifies xy coordinates relative to the widget's immediate parent. Since: 2.30 The AtkDocument interface should be supported by any object whose content is a representation or view of a document. The AtkDocument interface should appear on the toplevel container for the document content; however AtkDocument instances may be nested (i.e. an AtkDocument may be a descendant of another AtkDocument) in those cases where one document contains "embedded content" which can reasonably be considered a document in its own right. # Implements [`DocumentExt`](trait.DocumentExt.html) Trait containing all `Document` methods. # Implementors [`Document`](struct.Document.html), [`NoOpObject`](struct.NoOpObject.html) ## `attribute_name` a character string representing the name of the attribute whose value is being queried. # Returns a string value associated with the named attribute for this document, or NULL if a value for `attribute_name` has not been specified for this document. Gets an AtkAttributeSet which describes document-wide attributes as name-value pairs. # Returns An AtkAttributeSet containing the explicitly set name-value-pair attributes associated with this document as a whole. # Returns current page number inside `self`. -1 if not implemented, not know by the implementor or irrelevant. Gets a `gpointer` that points to an instance of the DOM. It is up to the caller to check atk_document_get_type to determine how to cast this pointer. # Deprecated Since 2.12. `self` is already a representation of the document. Use it directly, or one of its children, as an instance of the DOM. # Returns a `gpointer` that points to an instance of the DOM. Gets a string indicating the document type. # Deprecated Since 2.12. Please use `Document::get_attributes` to ask for the document type if it applies. # Returns a string indicating the document type # Returns total page count of `self`. -1 if not implemented, not know by the implementor or irrelevant. ## `attribute_name` a character string representing the name of the attribute whose value is being set. ## `attribute_value` a string value to be associated with `attribute_name`. # Returns TRUE if `value` is successfully associated with `attribute_name` for this document, FALSE otherwise (e.g. if the document does not allow the attribute to be modified). The 'load-complete' signal is emitted when a pending load of a static document has completed. This signal is to be expected by ATK clients if and when AtkDocument implementors expose ATK_STATE_BUSY. If the state of an AtkObject which implements AtkDocument does not include ATK_STATE_BUSY, it should be safe for clients to assume that the AtkDocument's static contents are fully loaded into the container. (Dynamic document contents should be exposed via other signals.) The 'load-stopped' signal is emitted when a pending load of document contents is cancelled, paused, or otherwise interrupted by the user or application logic. It should not however be emitted while waiting for a resource (for instance while blocking on a file or network read) unless a user-significant timeout has occurred. The 'page-changed' signal is emitted when the current page of a document changes, e.g. pressing page up/down in a document viewer. ## `page_number` the new page number. If this value is unknown or not applicable, -1 should be provided. The 'reload' signal is emitted when the contents of a document is refreshed from its source. Once 'reload' has been emitted, a matching 'load-complete' or 'load-stopped' signal should follow, which clients may await before interrogating ATK for the latest document content. `EditableText` should be implemented by UI components which contain text which the user can edit, via the `Object` corresponding to that component (see `Object`). `EditableText` is a subclass of `Text`, and as such, an object which implements `EditableText` is by definition an `Text` implementor as well. See also: `Text` # Implements [`EditableTextExt`](trait.EditableTextExt.html) Trait containing all `EditableText` methods. # Implementors [`EditableText`](struct.EditableText.html), [`NoOpObject`](struct.NoOpObject.html) Copy text from `start_pos` up to, but not including `end_pos` to the clipboard. ## `start_pos` start position ## `end_pos` end position Copy text from `start_pos` up to, but not including `end_pos` to the clipboard and then delete from the widget. ## `start_pos` start position ## `end_pos` end position Delete text `start_pos` up to, but not including `end_pos`. ## `start_pos` start position ## `end_pos` end position Insert text at a given position. ## `string` the text to insert ## `length` the length of text to insert, in bytes ## `position` The caller initializes this to the position at which to insert the text. After the call it points at the position after the newly inserted text. Paste text from clipboard to specified `position`. ## `position` position to paste Sets the attributes for a specified range. See the ATK_ATTRIBUTE macros (such as `ATK_ATTRIBUTE_LEFT_MARGIN`) for examples of attributes that can be set. Note that other attributes that do not have corresponding ATK_ATTRIBUTE macros may also be set for certain text widgets. ## `attrib_set` an `AttributeSet` ## `start_offset` start of range in which to set attributes ## `end_offset` end of range in which to set attributes # Returns `true` if attributes successfully set for the specified range, otherwise `false` Set text contents of `self`. ## `string` string to set for text contents of `self` This object class is derived from AtkObject. It can be used as a basis for implementing accessible objects for GObjects which are not derived from `GtkWidget`. One example of its use is in providing an accessible object for GnomeCanvasItem in the GAIL library. # Implements [`GObjectAccessibleExt`](trait.GObjectAccessibleExt.html), [`AtkObjectExt`](trait.AtkObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `GObjectAccessible` methods. # Implementors [`GObjectAccessible`](struct.GObjectAccessible.html) Gets the accessible object for the specified `obj`. ## `obj` a `gobject::Object` # Returns a `Object` which is the accessible object for the `obj` Gets the GObject for which `self` is the accessible object. # Returns a `gobject::Object` which is the object for which `self` is the accessible object An ATK object which encapsulates a link or set of links (for instance in the case of client-side image maps) in a hypertext document. It may implement the AtkAction interface. AtkHyperlink may also be used to refer to inline embedded content, since it allows specification of a start and end offset within the host AtkHypertext object. # Implements [`HyperlinkExt`](trait.HyperlinkExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AtkActionExt`](trait.AtkActionExt.html) Trait containing all `Hyperlink` methods. # Implementors [`Hyperlink`](struct.Hyperlink.html) Gets the index with the hypertext document at which this link ends. # Returns the index with the hypertext document at which this link ends Gets the number of anchors associated with this hyperlink. # Returns the number of anchors associated with this hyperlink Returns the item associated with this hyperlinks nth anchor. For instance, the returned `Object` will implement `Text` if `self` is a text hyperlink, `Image` if `self` is an image hyperlink etc. Multiple anchors are primarily used by client-side image maps. ## `i` a (zero-index) integer specifying the desired anchor # Returns an `Object` associated with this hyperlinks i-th anchor Gets the index with the hypertext document at which this link begins. # Returns the index with the hypertext document at which this link begins Get a the URI associated with the anchor specified by `i` of `self`. Multiple anchors are primarily used by client-side image maps. ## `i` a (zero-index) integer specifying the desired anchor # Returns a string specifying the URI Indicates whether the link currently displays some or all of its content inline. Ordinary HTML links will usually return `false`, but an inline <src> HTML element will return `true`. # Returns whether or not this link displays its content inline. Since the document that a link is associated with may have changed this method returns `true` if the link is still valid (with respect to the document it references) and `false` otherwise. # Returns whether or not this link is still valid The signal link-activated is emitted when a link is activated. AtkHyperlinkImpl allows AtkObjects to refer to their associated AtkHyperlink instance, if one exists. AtkHyperlinkImpl differs from AtkHyperlink in that AtkHyperlinkImpl is an interface, whereas AtkHyperlink is a object type. The AtkHyperlinkImpl interface allows a client to query an AtkObject for the availability of an associated AtkHyperlink instance, and obtain that instance. It is thus particularly useful in cases where embedded content or inline content within a text object is present, since the embedding text object implements AtkHypertext and the inline/embedded objects are exposed as children which implement AtkHyperlinkImpl, in addition to their being obtainable via AtkHypertext:getLink followed by AtkHyperlink:getObject. The AtkHyperlinkImpl interface should be supported by objects exposed within the hierarchy as children of an AtkHypertext container which correspond to "links" or embedded content within the text. HTML anchors are not, for instance, normally exposed this way, but embedded images and components which appear inline in the content of a text object are. The AtkHyperlinkIface interface allows a means of determining which children are hyperlinks in this sense of the word, and for obtaining their corresponding AtkHyperlink object, from which the embedding range, URI, etc. can be obtained. To some extent this interface exists because, for historical reasons, AtkHyperlink was defined as an object type, not an interface. Thus, in order to interact with AtkObjects via AtkHyperlink semantics, a new interface was required. # Implements [`HyperlinkImplExt`](trait.HyperlinkImplExt.html) Trait containing all `HyperlinkImpl` methods. # Implementors [`HyperlinkImpl`](struct.HyperlinkImpl.html) Gets the hyperlink associated with this object. # Returns an AtkHyperlink object which points to this implementing AtkObject. An interface used for objects which implement linking between multiple resource or content locations, or multiple 'markers' within a single document. A Hypertext instance is associated with one or more Hyperlinks, which are associated with particular offsets within the Hypertext's included content. While this interface is derived from Text, there is no requirement that Hypertext instances have textual content; they may implement Image as well, and Hyperlinks need not have non-zero text offsets. # Implements [`HypertextExt`](trait.HypertextExt.html) Trait containing all `Hypertext` methods. # Implementors [`Hypertext`](struct.Hypertext.html), [`NoOpObject`](struct.NoOpObject.html) Gets the link in this hypertext document at index `link_index` ## `link_index` an integer specifying the desired link # Returns the link in this hypertext document at index `link_index` Gets the index into the array of hyperlinks that is associated with the character specified by `char_index`. ## `char_index` a character index # Returns an index into the array of hyperlinks in `self`, or -1 if there is no hyperlink associated with this character. Gets the number of links within this hypertext document. # Returns the number of links within this hypertext document The "link-selected" signal is emitted by an AtkHyperText object when one of the hyperlinks associated with the object is selected. ## `arg1` the index of the hyperlink which is selected `Image` should be implemented by `Object` subtypes on behalf of components which display image/pixmap information onscreen, and which provide information (other than just widget borders, etc.) via that image content. For instance, icons, buttons with icons, toolbar elements, and image viewing panes typically should implement `Image`. `Image` primarily provides two types of information: coordinate information (useful for screen review mode of screenreaders, and for use by onscreen magnifiers), and descriptive information. The descriptive information is provided for alternative, text-only presentation of the most significant information present in the image. # Implements [`AtkImageExt`](trait.AtkImageExt.html) Trait containing all `Image` methods. # Implementors [`Image`](struct.Image.html), [`NoOpObject`](struct.NoOpObject.html) Get a textual description of this image. # Returns a string representing the image description # Returns a string corresponding to the POSIX LC_MESSAGES locale used by the image description, or `None` if the image does not specify a locale. Gets the position of the image in the form of a point specifying the images top-left corner. ## `x` address of `gint` to put x coordinate position; otherwise, -1 if value cannot be obtained. ## `y` address of `gint` to put y coordinate position; otherwise, -1 if value cannot be obtained. ## `coord_type` specifies whether the coordinates are relative to the screen or to the components top level window Get the width and height in pixels for the specified image. The values of `width` and `height` are returned as -1 if the values cannot be obtained (for instance, if the object is not onscreen). ## `width` filled with the image width, or -1 if the value cannot be obtained. ## `height` filled with the image height, or -1 if the value cannot be obtained. Sets the textual description for this image. ## `description` a string description to set for `self` # Returns boolean TRUE, or FALSE if operation could not be completed. Describes the layer of a component These enumerated "layer values" are used when determining which UI rendering layer a component is drawn into, which can help in making determinations of when components occlude one another. The object does not have a layer This layer is reserved for the desktop background This layer is used for Canvas components This layer is normally used for components This layer is used for layered components This layer is used for popup components, such as menus This layer is reserved for future use. This layer is used for toplevel windows. A set of utility functions for thread locking. This interface and all his related methods are deprecated since 2.12. # Implements [`AtkMiscExt`](trait.AtkMiscExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Misc` methods. # Implementors [`Misc`](struct.Misc.html) Obtain the singleton instance of AtkMisc for this application. # Deprecated Since 2.12. # Returns The singleton instance of AtkMisc for this application. Take the thread mutex for the GUI toolkit, if one exists. (This method is implemented by the toolkit ATK implementation layer; for instance, for GTK+, GAIL implements this via GDK_THREADS_ENTER). # Deprecated Since 2.12. Release the thread mutex for the GUI toolkit, if one exists. This method, and atk_misc_threads_enter, are needed in some situations by threaded application code which services ATK requests, since fulfilling ATK requests often requires calling into the GUI toolkit. If a long-running or potentially blocking call takes place inside such a block, it should be bracketed by atk_misc_threads_leave/atk_misc_threads_enter calls. (This method is implemented by the toolkit ATK implementation layer; for instance, for GTK+, GAIL implements this via GDK_THREADS_LEAVE). # Deprecated Since 2.12. An AtkNoOpObject is an AtkObject which purports to implement all ATK interfaces. It is the type of AtkObject which is created if an accessible object is requested for an object type for which no factory type is specified. # Implements [`AtkObjectExt`](trait.AtkObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AtkActionExt`](trait.AtkActionExt.html), [`ComponentExt`](trait.ComponentExt.html), [`DocumentExt`](trait.DocumentExt.html), [`EditableTextExt`](trait.EditableTextExt.html), [`HypertextExt`](trait.HypertextExt.html), [`AtkImageExt`](trait.AtkImageExt.html), [`SelectionExt`](trait.SelectionExt.html), [`TableExt`](trait.TableExt.html), [`TableCellExt`](trait.TableCellExt.html), [`TextExt`](trait.TextExt.html), [`ValueExt`](trait.ValueExt.html), [`AtkWindowExt`](trait.AtkWindowExt.html) Provides a default (non-functioning stub) `Object`. Application maintainers should not use this method. ## `obj` a `gobject::Object` # Returns a default (non-functioning stub) `Object` The AtkObjectFactory which creates an AtkNoOpObject. An instance of this is created by an AtkRegistry if no factory type has not been specified to create an accessible object of a particular type. # Implements [`ObjectFactoryExt`](trait.ObjectFactoryExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates an instance of an `ObjectFactory` which generates primitive (non-functioning) `AtkObjects`. # Returns an instance of an `ObjectFactory` This class is the primary class for accessibility support via the Accessibility ToolKit (ATK). Objects which are instances of `Object` (or instances of AtkObject-derived types) are queried for properties which relate basic (and generic) properties of a UI component such as name and description. Instances of `Object` may also be queried as to whether they implement other ATK interfaces (e.g. `Action`, `Component`, etc.), as appropriate to the role which a given UI component plays in a user interface. All UI components in an application which provide useful information or services to the user must provide corresponding `Object` instances on request (in GTK+, for instance, usually on a call to `gtk_widget_get_accessible` ()), either via ATK support built into the toolkit for the widget class or ancestor class, or in the case of custom widgets, if the inherited `Object` implementation is insufficient, via instances of a new `Object` subclass. See also: `ObjectFactory`, `Registry`. (GTK+ users see also ``GtkAccessible``). # Implements [`AtkObjectExt`](trait.AtkObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Object` methods. # Implementors [`GObjectAccessible`](struct.GObjectAccessible.html), [`NoOpObject`](struct.NoOpObject.html), [`Object`](struct.Object.html), [`Plug`](struct.Plug.html), [`Socket`](struct.Socket.html), [`TableCell`](struct.TableCell.html), [`Window`](struct.Window.html) Adds a relationship of the specified type with the specified target. ## `relationship` The `RelationType` of the relation ## `target` The `Object` which is to be the target of the relation. # Returns TRUE if the relationship is added. # Deprecated Since 2.12. Connect directly to property-change or notify signals. ## `handler` a function to be called when a property changes its value # Returns a `guint` which is the handler id used in `AtkObjectExt::remove_property_change_handler` Get a list of properties applied to this object as a whole, as an `AttributeSet` consisting of name-value pairs. As such these attributes may be considered weakly-typed properties or annotations, as distinct from strongly-typed object data available via other get/set methods. Not all objects have explicit "name-value pair" `AttributeSet` properties. # Returns an `AttributeSet` consisting of all explicit properties/annotations applied to the object, or an empty set if the object has no name-value pair attributes assigned to it. This `atkattributeset` should be freed by a call to `Attribute::set_free`. Gets the accessible description of the accessible. # Returns a character string representing the accessible description of the accessible. Gets the 0-based index of this accessible in its parent; returns -1 if the accessible does not have an accessible parent. # Returns an integer which is the index of the accessible in its parent Gets the layer of the accessible. # Deprecated Use atk_component_get_layer instead. # Returns an `Layer` which is the layer of the accessible Gets the zorder of the accessible. The value G_MININT will be returned if the layer of the accessible is not ATK_LAYER_MDI. # Deprecated Use atk_component_get_mdi_zorder instead. # Returns a gint which is the zorder of the accessible, i.e. the depth at which the component is shown in relation to other components in the same container. Gets the number of accessible children of the accessible. # Returns an integer representing the number of accessible children of the accessible. Gets the accessible name of the accessible. # Returns a character string representing the accessible name of the object. Gets a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of `self`. # Returns a UTF-8 string indicating the POSIX-style LC_MESSAGES locale of `self`. Gets the accessible parent of the accessible. By default this is the one assigned with `AtkObjectExt::set_parent`, but it is assumed that ATK implementors have ways to get the parent of the object without the need of assigning it manually with `AtkObjectExt::set_parent`, and will return it with this method. If you are only interested on the parent assigned with `AtkObjectExt::set_parent`, use `AtkObjectExt::peek_parent`. # Returns an `Object` representing the accessible parent of the accessible Gets the role of the accessible. # Returns an `Role` which is the role of the accessible This function is called when implementing subclasses of `Object`. It does initialization required for the new object. It is intended that this function should called only in the ...`_new` functions used to create an instance of a subclass of `Object` ## `data` a `gpointer` which identifies the object for which the AtkObject was created. Emits a state-change signal for the specified state. Note that as a general rule when the state of an existing object changes, emitting a notification is expected. ## `state` an `State` whose state is changed ## `value` a gboolean which indicates whether the state is being set on or off Gets the accessible parent of the accessible, if it has been manually assigned with atk_object_set_parent. Otherwise, this function returns `None`. This method is intended as an utility for ATK implementors, and not to be exposed to accessible tools. See `AtkObjectExt::get_parent` for further reference. # Returns an `Object` representing the accessible parent of the accessible if assigned Gets a reference to the specified accessible child of the object. The accessible children are 0-based so the first accessible child is at index 0, the second at index 1 and so on. ## `i` a gint representing the position of the child, starting from 0 # Returns an `Object` representing the specified accessible child of the accessible. Gets the `RelationSet` associated with the object. # Returns an `RelationSet` representing the relation set of the object. Gets a reference to the state set of the accessible; the caller must unreference it when it is no longer needed. # Returns a reference to an `StateSet` which is the state set of the accessible # Deprecated Since 2.12. Removes a property change handler. ## `handler_id` a guint which identifies the handler to be removed. Removes a relationship of the specified type with the specified target. ## `relationship` The `RelationType` of the relation ## `target` The `Object` which is the target of the relation to be removed. # Returns TRUE if the relationship is removed. Sets the accessible description of the accessible. You can't set the description to NULL. This is reserved for the initial value. In this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to a empty value you can use "". ## `description` a character string to be set as the accessible description Sets the accessible name of the accessible. You can't set the name to NULL. This is reserved for the initial value. In this aspect NULL is similar to ATK_ROLE_UNKNOWN. If you want to set the name to a empty value you can use "". ## `name` a character string to be set as the accessible name Sets the accessible parent of the accessible. `parent` can be NULL. ## `parent` an `Object` to be set as the accessible parent Sets the role of the accessible. ## `role` an `Role` to be set as the role The "active-descendant-changed" signal is emitted by an object which has the state ATK_STATE_MANAGES_DESCENDANTS when the focus object in the object changes. For instance, a table will emit the signal when the cell in the table which has focus changes. ## `arg1` the newly focused object. The signal "children-changed" is emitted when a child is added or removed form an object. It supports two details: "add" and "remove" ## `arg1` The index of the added or removed child. The value can be -1. This is used if the value is not known by the implementor when the child is added/removed or irrelevant. ## `arg2` A gpointer to the child AtkObject which was added or removed. If the child was removed, it is possible that it is not available for the implementor. In that case this pointer can be NULL. The signal "property-change" is emitted when an object's property value changes. `arg1` contains an `PropertyValues` with the name and the new value of the property whose value has changed. Note that, as with GObject notify, getting this signal does not guarantee that the value of the property has actually changed; it may also be emitted when the setter of the property is called to reinstate the previous value. Toolkit implementor note: ATK implementors should use `gobject::ObjectExt::notify` to emit property-changed notifications. `Object::property-changed` is needed by the implementation of `atk_add_global_event_listener` because GObject notify doesn't support emission hooks. ## `arg1` an `PropertyValues` containing the new value of the property which changed. The "state-change" signal is emitted when an object's state changes. The detail value identifies the state type which has changed. ## `arg1` The name of the state which has changed ## `arg2` A boolean which indicates whether the state has been set or unset. The "visible-data-changed" signal is emitted when the visual appearance of the object changed. Table caption. # Deprecated Since 1.3. Use table-caption-object instead. Table caption. # Deprecated Since 1.3. Use table-caption-object instead. Accessible table column description. # Deprecated Since 2.12. Use `Table::get_column_description` and `Table::set_column_description` instead. Accessible table column description. # Deprecated Since 2.12. Use `Table::get_column_description` and `Table::set_column_description` instead. Accessible table column header. # Deprecated Since 2.12. Use `Table::get_column_header` and `Table::set_column_header` instead. Accessible table column header. # Deprecated Since 2.12. Use `Table::get_column_header` and `Table::set_column_header` instead. Accessible table row description. # Deprecated Since 2.12. Use `Table::get_row_description` and `Table::set_row_description` instead. Accessible table row description. # Deprecated Since 2.12. Use `Table::get_row_description` and `Table::set_row_description` instead. Accessible table row header. # Deprecated Since 2.12. Use `Table::get_row_header` and `Table::set_row_header` instead. Accessible table row header. # Deprecated Since 2.12. Use `Table::get_row_header` and `Table::set_row_header` instead. Numeric value of this object, in case being and AtkValue. # Deprecated Since 2.12. Use `Value::get_value_and_text` to get the value, and value-changed signal to be notified on their value changes. Numeric value of this object, in case being and AtkValue. # Deprecated Since 2.12. Use `Value::get_value_and_text` to get the value, and value-changed signal to be notified on their value changes. This class is the base object class for a factory used to create an accessible object for a specific GType. The function `RegistryExt::set_factory_type` is normally called to store in the registry the factory type to be used to create an accessible of a particular GType. # Implements [`ObjectFactoryExt`](trait.ObjectFactoryExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `ObjectFactory` methods. # Implementors [`NoOpObjectFactory`](struct.NoOpObjectFactory.html), [`ObjectFactory`](struct.ObjectFactory.html) Provides an `Object` that implements an accessibility interface on behalf of `obj` ## `obj` a `gobject::Object` # Returns an `Object` that implements an accessibility interface on behalf of `obj` Gets the GType of the accessible which is created by the factory. # Returns the type of the accessible which is created by the `self`. The value G_TYPE_INVALID is returned if no type if found. Inform `self` that it is no longer being used to create accessibles. When called, `self` may need to inform `AtkObjects` which it has created that they need to be re-instantiated. Note: primarily used for runtime replacement of `AtkObjectFactorys` in object registries. See `Socket` # Implements [`AtkPlugExt`](trait.AtkPlugExt.html), [`AtkObjectExt`](trait.AtkObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ComponentExt`](trait.ComponentExt.html) Trait containing all `Plug` methods. # Implementors [`Plug`](struct.Plug.html) Gets the unique ID of an `Plug` object, which can be used to embed inside of an `Socket` using `AtkSocketExt::embed`. Internally, this calls a class function that should be registered by the IPC layer (usually at-spi2-atk). The implementor of an `Plug` object should call this function (after atk-bridge is loaded) and pass the value to the process implementing the `Socket`, so it could embed the plug. # Returns the unique ID for the plug `Range` are used on `Value`, in order to represent the full range of a given component (for example an slider or a range control), or to define each individual subrange this full range is splitted if available. See `Value` documentation for further details. Creates a new `Range`. ## `lower_limit` inferior limit for this range ## `upper_limit` superior limit for this range ## `description` human readable description of this range. # Returns a new `Range` Returns a new `Range` that is a exact copy of `self` # Returns a new `Range` copy of `self` Free `self` Returns the human readable description of `self` # Returns the human-readable description of `self` Returns the lower limit of `self` # Returns the lower limit of `self` Returns the upper limit of `self` # Returns the upper limit of `self` A data structure for holding a rectangle. Those coordinates are relative to the component top-level parent. The AtkRegistry is normally used to create appropriate ATK "peers" for user interface components. Application developers usually need only interact with the AtkRegistry by associating appropriate ATK implementation classes with GObject classes via the atk_registry_set_factory_type call, passing the appropriate GType for application custom widget classes. # Implements [`RegistryExt`](trait.RegistryExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Registry` methods. # Implementors [`Registry`](struct.Registry.html) Gets an `ObjectFactory` appropriate for creating `AtkObjects` appropriate for `type_`. ## `type_` a `glib::Type` with which to look up the associated `ObjectFactory` # Returns an `ObjectFactory` appropriate for creating `AtkObjects` appropriate for `type_`. Provides a `glib::Type` indicating the `ObjectFactory` subclass associated with `type_`. ## `type_` a `glib::Type` with which to look up the associated `ObjectFactory` subclass # Returns a `glib::Type` associated with type `type_` Associate an `ObjectFactory` subclass with a `glib::Type`. Note: The associated `factory_type` will thereafter be responsible for the creation of new `Object` implementations for instances appropriate for `type_`. ## `type_` an `Object` type ## `factory_type` an `ObjectFactory` type to associate with `type_`. Must implement AtkObject appropriate for `type_`. An AtkRelation describes a relation between an object and one or more other objects. The actual relations that an object has with other objects are defined as an AtkRelationSet, which is a set of AtkRelations. # Implements [`RelationExt`](trait.RelationExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Relation` methods. # Implementors [`Relation`](struct.Relation.html) Create a new relation for the specified key and the specified list of targets. See also `AtkObjectExt::add_relationship`. ## `targets` an array of pointers to `AtkObjects` ## `n_targets` number of `AtkObjects` pointed to by `targets` ## `relationship` an `RelationType` with which to create the new `Relation` # Returns a pointer to a new `Relation` Adds the specified AtkObject to the target for the relation, if it is not already present. See also `AtkObjectExt::add_relationship`. ## `target` an `Object` Gets the type of `self` # Returns the type of `self` Gets the target list of `self` # Returns the target list of `self` Remove the specified AtkObject from the target for the relation. ## `target` an `Object` # Returns TRUE if the removal is successful. The AtkRelationSet held by an object establishes its relationships with objects beyond the normal "parent/child" hierarchical relationships that all user interface objects have. AtkRelationSets establish whether objects are labelled or controlled by other components, share group membership with other components (for instance within a radio-button group), or share content which "flows" between them, among other types of possible relationships. # Implements [`RelationSetExt`](trait.RelationSetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `RelationSet` methods. # Implementors [`RelationSet`](struct.RelationSet.html) Creates a new empty relation set. # Returns a new `RelationSet` Add a new relation to the current relation set if it is not already present. This function ref's the AtkRelation so the caller of this function should unref it to ensure that it will be destroyed when the AtkRelationSet is destroyed. ## `relation` an `Relation` Add a new relation of the specified type with the specified target to the current relation set if the relation set does not contain a relation of that type. If it is does contain a relation of that typea the target is added to the relation. ## `relationship` an `RelationType` ## `target` an `Object` Determines whether the relation set contains a relation that matches the specified type. ## `relationship` an `RelationType` # Returns `true` if `relationship` is the relationship type of a relation in `self`, `false` otherwise Determines whether the relation set contains a relation that matches the specified pair formed by type `relationship` and object `target`. ## `relationship` an `RelationType` ## `target` an `Object` # Returns `true` if `self` contains a relation with the relationship type `relationship` with an object `target`, `false` otherwise Determines the number of relations in a relation set. # Returns an integer representing the number of relations in the set. Determines the relation at the specified position in the relation set. ## `i` a gint representing a position in the set, starting from 0. # Returns a `Relation`, which is the relation at position i in the set. Finds a relation that matches the specified type. ## `relationship` an `RelationType` # Returns an `Relation`, which is a relation matching the specified type. Removes a relation from the relation set. This function unref's the `Relation` so it will be deleted unless there is another reference to it. ## `relation` an `Relation` Describes the type of the relation Not used, represens "no relationship" or an error condition. Indicates an object controlled by one or more target objects. Indicates an object is an controller for one or more target objects. Indicates an object is a label for one or more target objects. Indicates an object is labelled by one or more target objects. Indicates an object is a member of a group of one or more target objects. Indicates an object is a cell in a treetable which is displayed because a cell in the same column is expanded and identifies that cell. Indicates that the object has content that flows logically to another AtkObject in a sequential way, (for instance text-flow). Indicates that the object has content that flows logically from another AtkObject in a sequential way, (for instance text-flow). Indicates a subwindow attached to a component but otherwise has no connection in the UI heirarchy to that component. Indicates that the object visually embeds another object's content, i.e. this object's content flows around another's content. Reciprocal of `RelationType::Embeds`, indicates that this object's content is visualy embedded in another object. Indicates that an object is a popup for another object. Indicates that an object is a parent window of another object. Reciprocal of `RelationType::DescriptionFor`. Indicates that one or more target objects provide descriptive information about this object. This relation type is most appropriate for information that is not essential as its presentation may be user-configurable and/or limited to an on-demand mechanism such as an assistive technology command. For brief, essential information such as can be found in a widget's on-screen label, use `RelationType::LabelledBy`. For an on-screen error message, use `RelationType::ErrorMessage`. For lengthy extended descriptive information contained in an on-screen object, consider using `RelationType::Details` as assistive technologies may provide a means for the user to navigate to objects containing detailed descriptions so that their content can be more closely reviewed. Reciprocal of `RelationType::DescribedBy`. Indicates that this object provides descriptive information about the target object(s). See also `RelationType::DetailsFor` and `RelationType::ErrorFor`. Indicates an object is a cell in a treetable and is expanded to display other cells in the same column. Reciprocal of `RelationType::DetailsFor`. Indicates that this object has a detailed or extended description, the contents of which can be found in the target object(s). This relation type is most appropriate for information that is sufficiently lengthy as to make navigation to the container of that information desirable. For less verbose information suitable for announcement only, see `RelationType::DescribedBy`. If the detailed information describes an error condition, `RelationType::ErrorFor` should be used instead. `Since`: ATK-2.26. Reciprocal of `RelationType::Details`. Indicates that this object provides a detailed or extended description about the target object(s). See also `RelationType::DescriptionFor` and `RelationType::ErrorFor`. `Since`: ATK-2.26. Reciprocal of `RelationType::ErrorFor`. Indicates that this object has one or more errors, the nature of which is described in the contents of the target object(s). Objects that have this relation type should also contain `StateType::InvalidEntry` in their `StateSet`. `Since`: ATK-2.26. Reciprocal of `RelationType::ErrorMessage`. Indicates that this object contains an error message describing an invalid condition in the target object(s). `Since`: ATK_2.26. Not used, this value indicates the end of the enumeration. Describes the role of an object These are the built-in enumerated roles that UI components can have in ATK. Other roles may be added at runtime, so an AtkRole >= ATK_ROLE_LAST_DEFINED is not necessarily an error. Invalid role A label which represents an accelerator An object which is an alert to the user. Assistive Technologies typically respond to ATK_ROLE_ALERT by reading the entire onscreen contents of containers advertising this role. Should be used for warning dialogs, etc. An object which is an animated image An arrow in one of the four cardinal directions An object that displays a calendar and allows the user to select a date An object that can be drawn into and is used to trap events A choice that can be checked or unchecked and provides a separate indicator for the current state A menu item with a check box A specialized dialog that lets the user choose a color The header for a column of data A collapsible list of choices the user can select from An object whose purpose is to allow a user to edit a date An inconifed internal frame within a DESKTOP_PANE A pane that supports internal frames and iconified versions of those internal frames An object whose purpose is to allow a user to set a value A top level window with title bar and a border A pane that allows the user to navigate through and select the contents of a directory An object used for drawing custom user interface elements A specialized dialog that lets the user choose a file A object that fills up space in a user interface A specialized dialog that lets the user choose a font A top level window with a title bar, border, menubar, etc. A pane that is guaranteed to be painted on top of all panes beneath it A document container for HTML, whose children represent the document content A small fixed size picture, typically used to decorate components An object whose primary purpose is to display an image A frame-like object that is clipped by a desktop pane An object used to present an icon or short string in an interface A specialized pane that allows its children to be drawn in layers, providing a form of stacking order An object that presents a list of objects to the user and allows the user to select one or more of them An object that represents an element of a list An object usually found inside a menu bar that contains a list of actions the user can choose from An object usually drawn at the top of the primary dialog box of an application that contains a list of menus the user can choose from An object usually contained in a menu that presents an action the user can choose A specialized pane whose primary use is inside a DIALOG An object that is a child of a page tab list An object that presents a series of panels (or page tabs), one at a time, through some mechanism provided by the object A generic container that is often used to group objects A text object uses for passwords, or other places where the text content is not shown visibly to the user A temporary window that is usually used to offer the user a list of choices, and then hides when the user selects one of those choices An object used to indicate how much of a task has been completed An object the user can manipulate to tell the application to do something A specialized check box that will cause other radio buttons in the same group to become unchecked when this one is checked A check menu item which belongs to a group. At each instant exactly one of the radio menu items from a group is selected A specialized pane that has a glass pane and a layered pane as its children The header for a row of data An object usually used to allow a user to incrementally view a large amount of data. An object that allows a user to incrementally view a large amount of information An object usually contained in a menu to provide a visible and logical separation of the contents in a menu An object that allows the user to select from a bounded range A specialized panel that presents two other panels at the same time An object used to get an integer or floating point number from the user An object which reports messages of minor importance to the user An object used to represent information in terms of rows and columns A cell in a table The header for a column of a table The header for a row of a table A menu item used to tear off and reattach its menu An object that represents an accessible terminal. `Since`: ATK-0.6 An interactive widget that supports multiple lines of text and optionally accepts user input, but whose purpose is not to solicit user input. Thus ATK_ROLE_TEXT is appropriate for the text view in a plain text editor but inappropriate for an input field in a dialog box or web form. For widgets whose purpose is to solicit input from the user, see ATK_ROLE_ENTRY and ATK_ROLE_PASSWORD_TEXT. For generic objects which display a brief amount of textual information, see ATK_ROLE_STATIC. A specialized push button that can be checked or unchecked, but does not provide a separate indicator for the current state A bar or palette usually composed of push buttons or toggle buttons An object that provides information about another object An object used to represent hierarchical information to the user An object capable of expanding and collapsing rows as well as showing multiple columns of data. `Since`: ATK-0.7 The object contains some Accessible information, but its role is not known An object usually used in a scroll pane A top level window with no title or border. An object that serves as a document header. `Since`: ATK-1.1.1 An object that serves as a document footer. `Since`: ATK-1.1.1 An object which is contains a paragraph of text content. `Since`: ATK-1.1.1 An object which describes margins and tab stops, etc. for text objects which it controls (should have CONTROLLER_FOR relation to such). `Since`: ATK-1.1.1 The object is an application object, which may contain `Role::Frame` objects or other types of accessibles. The root accessible of any application's ATK hierarchy should have ATK_ROLE_APPLICATION. `Since`: ATK-1.1.4 The object is a dialog or list containing items for insertion into an entry widget, for instance a list of words for completion of a text entry. `Since`: ATK-1.3 The object is an editable text object in a toolbar. `Since`: ATK-1.5 The object is an embedded container within a document or panel. This role is a grouping "hint" indicating that the contained objects share a context. `Since`: ATK-1.7.2 The object is a component whose textual content may be entered or modified by the user, provided `StateType::Editable` is present. `Since`: ATK-1.11 The object is a graphical depiction of quantitative data. It may contain multiple subelements whose attributes and/or description may be queried to obtain both the quantitative data and information about how the data is being presented. The LABELLED_BY relation is particularly important in interpreting objects of this type, as is the accessible-description property. `Since`: ATK-1.11 The object contains descriptive information, usually textual, about another user interface element such as a table, chart, or image. `Since`: ATK-1.11 The object is a visual frame or container which contains a view of document content. Document frames may occur within another Document instance, in which case the second document may be said to be embedded in the containing instance. HTML frames are often ROLE_DOCUMENT_FRAME. Either this object, or a singleton descendant, should implement the Document interface. `Since`: ATK-1.11 The object serves as a heading for content which follows it in a document. The 'heading level' of the heading, if availabe, may be obtained by querying the object's attributes. The object is a containing instance which encapsulates a page of information. `Role::Page` is used in documents and content which support a paginated navigation model. `Since`: ATK-1.11 The object is a containing instance of document content which constitutes a particular 'logical' section of the document. The type of content within a section, and the nature of the section division itself, may be obtained by querying the object's attributes. Sections may be nested. `Since`: ATK-1.11 The object is redundant with another object in the hierarchy, and is exposed for purely technical reasons. Objects of this role should normally be ignored by clients. `Since`: ATK-1.11 The object is a container for form controls, for instance as part of a web form or user-input form within a document. This role is primarily a tag/convenience for clients when navigating complex documents, it is not expected that ordinary GUI containers will always have ATK_ROLE_FORM. `Since`: ATK-1.12.0 The object is a hypertext anchor, i.e. a "link" in a hypertext document. Such objects are distinct from 'inline' content which may also use the Hypertext/Hyperlink interfaces to indicate the range/location within a text object where an inline or embedded object lies. `Since`: ATK-1.12.1 The object is a window or similar viewport which is used to allow composition or input of a 'complex character', in other words it is an "input method window." `Since`: ATK-1.12.1 A row in a table. `Since`: ATK-2.1.0 An object that represents an element of a tree. `Since`: ATK-2.1.0 A document frame which contains a spreadsheet. `Since`: ATK-2.1.0 A document frame which contains a presentation or slide content. `Since`: ATK-2.1.0 A document frame which contains textual content, such as found in a word processing application. `Since`: ATK-2.1.0 A document frame which contains HTML or other markup suitable for display in a web browser. `Since`: ATK-2.1.0 A document frame which contains email content to be displayed or composed either in plain text or HTML. `Since`: ATK-2.1.0 An object found within a document and designed to present a comment, note, or other annotation. In some cases, this object might not be visible until activated. `Since`: ATK-2.1.0 A non-collapsible list of choices the user can select from. `Since`: ATK-2.1.0 A group of related widgets. This group typically has a label. `Since`: ATK-2.1.0 An image map object. Usually a graphic with multiple hotspots, where each hotspot can be activated resulting in the loading of another document or section of a document. `Since`: ATK-2.1.0 A transitory object designed to present a message to the user, typically at the desktop level rather than inside a particular application. `Since`: ATK-2.1.0 An object designed to present a message to the user within an existing window. `Since`: ATK-2.1.0 A bar that serves as a level indicator to, for instance, show the strength of a password or the state of a battery. `Since`: ATK-2.7.3 A bar that serves as the title of a window or a dialog. `Since`: ATK-2.12 An object which contains a text section that is quoted from another source. `Since`: ATK-2.12 An object which represents an audio element. `Since`: ATK-2.12 An object which represents a video element. `Since`: ATK-2.12 A definition of a term or concept. `Since`: ATK-2.12 A section of a page that consists of a composition that forms an independent part of a document, page, or site. Examples: A blog entry, a news story, a forum post. `Since`: ATK-2.12 A region of a web page intended as a navigational landmark. This is designed to allow Assistive Technologies to provide quick navigation among key regions within a document. `Since`: ATK-2.12 A text widget or container holding log content, such as chat history and error logs. In this role there is a relationship between the arrival of new items in the log and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. `Since`: ATK-2.12 A container where non-essential information changes frequently. Common usages of marquee include stock tickers and ad banners. The primary difference between a marquee and a log is that logs usually have a meaningful order or sequence of important content changes. `Since`: ATK-2.12 A text widget or container that holds a mathematical expression. `Since`: ATK-2.12 A widget whose purpose is to display a rating, such as the number of stars associated with a song in a media player. Objects of this role should also implement AtkValue. `Since`: ATK-2.12 An object containing a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. `Since`: ATK-2.12 An object that represents a list of term-value groups. A term-value group represents a individual description and consist of one or more names (ATK_ROLE_DESCRIPTION_TERM) followed by one or more values (ATK_ROLE_DESCRIPTION_VALUE). For each list, there should not be more than one group with the same term name. `Since`: ATK-2.12 An object that represents a term or phrase with a corresponding definition. `Since`: ATK-2.12 An object that represents the description, definition or value of a term. `Since`: ATK-2.12 A generic non-container object whose purpose is to display a brief amount of information to the user and whose role is known by the implementor but lacks semantic value for the user. Examples in which ATK_ROLE_STATIC is appropriate include the message displayed in a message box and an image used as an alternative means to display text. ATK_ROLE_STATIC should not be applied to widgets which are traditionally interactive, objects which display a significant amount of content, or any object which has an accessible relation pointing to another object. Implementors should expose the displayed information through the accessible name of the object. If doing so seems inappropriate, it may indicate that a different role should be used. For labels which describe another widget, see ATK_ROLE_LABEL. For text views, see ATK_ROLE_TEXT. For generic containers, see ATK_ROLE_PANEL. For objects whose role is not known by the implementor, see ATK_ROLE_UNKNOWN. `Since`: ATK-2.16. An object that represents a mathematical fraction. An object that represents a mathematical expression displayed with a radical. `Since`: ATK-2.16. An object that contains text that is displayed as a subscript. `Since`: ATK-2.16. An object that contains text that is displayed as a superscript. `Since`: ATK-2.16. An object that contains the text of a footnote. `Since`: ATK-2.26. not a valid role, used for finding end of the enumeration Specifies where an object should be placed on the screen when using scroll_to. Scroll the object vertically and horizontally to the top left corner of the window. Scroll the object vertically and horizontally to the bottom right corner of the window. Scroll the object vertically to the top edge of the window. Scroll the object vertically to the bottom edge of the window. Scroll the object vertically and horizontally to the left edge of the window. Scroll the object vertically and horizontally to the right edge of the window. Scroll the object vertically and horizontally so that as much as possible of the object becomes visible. The exact placement is determined by the application. Feature: `v2_30` `Selection` should be implemented by UI components with children which are exposed by `atk_object_ref_child` and `atk_object_get_n_children`, if the use of the parent UI component ordinarily involves selection of one or more of the objects corresponding to those `Object` children - for example, selectable lists. Note that other types of "selection" (for instance text selection) are accomplished a other ATK interfaces - `Selection` is limited to the selection/deselection of children. # Implements [`SelectionExt`](trait.SelectionExt.html) Trait containing all `Selection` methods. # Implementors [`NoOpObject`](struct.NoOpObject.html), [`Selection`](struct.Selection.html) Adds the specified accessible child of the object to the object's selection. ## `i` a `gint` specifying the child index. # Returns TRUE if success, FALSE otherwise. Clears the selection in the object so that no children in the object are selected. # Returns TRUE if success, FALSE otherwise. Gets the number of accessible children currently selected. Note: callers should not rely on `None` or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the `atk_get_accessible_value` convenience method. # Returns a gint representing the number of items selected, or 0 if `self` does not implement this interface. Determines if the current child of this object is selected Note: callers should not rely on `None` or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the `atk_get_accessible_value` convenience method. ## `i` a `gint` specifying the child index. # Returns a gboolean representing the specified child is selected, or 0 if `self` does not implement this interface. Gets a reference to the accessible object representing the specified selected child of the object. Note: callers should not rely on `None` or on a zero value for indication of whether AtkSelectionIface is implemented, they should use type checking/interface checking macros or the `atk_get_accessible_value` convenience method. ## `i` a `gint` specifying the index in the selection set. (e.g. the ith selection as opposed to the ith child). # Returns an `Object` representing the selected accessible, or `None` if `self` does not implement this interface. Removes the specified child of the object from the object's selection. ## `i` a `gint` specifying the index in the selection set. (e.g. the ith selection as opposed to the ith child). # Returns TRUE if success, FALSE otherwise. Causes every child of the object to be selected if the object supports multiple selections. # Returns TRUE if success, FALSE otherwise. The "selection-changed" signal is emitted by an object which implements AtkSelection interface when the selection changes. Together with `Plug`, `Socket` provides the ability to embed accessibles from one process into another in a fashion that is transparent to assistive technologies. `Socket` works as the container of `Plug`, embedding it using the method `AtkSocketExt::embed`. Any accessible contained in the `Plug` will appear to the assistive technologies as being inside the application that created the `Socket`. The communication between a `Socket` and a `Plug` is done by the IPC layer of the accessibility framework, normally implemented by the D-Bus based implementation of AT-SPI (at-spi2). If that is the case, at-spi-atk2 is the responsible to implement the abstract methods `AtkPlugExt::get_id` and `AtkSocketExt::embed`, so an ATK implementor shouldn't reimplement them. The process that contains the `Plug` is responsible to send the ID returned by `atk_plug_id` to the process that contains the `Socket`, so it could call the method `AtkSocketExt::embed` in order to embed it. For the same reasons, an implementor doesn't need to implement `AtkObjectExt::get_n_accessible_children` and `AtkObjectExt::ref_accessible_child`. All the logic related to those functions will be implemented by the IPC layer. # Implements [`AtkSocketExt`](trait.AtkSocketExt.html), [`AtkObjectExt`](trait.AtkObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ComponentExt`](trait.ComponentExt.html) Trait containing all `Socket` methods. # Implementors [`Socket`](struct.Socket.html) Embeds the children of an `Plug` as the children of the `Socket`. The plug may be in the same process or in a different process. The class item used by this function should be filled in by the IPC layer (usually at-spi2-atk). The implementor of the AtkSocket should call this function and pass the id for the plug as returned by `AtkPlugExt::get_id`. It is the responsibility of the application to pass the plug id on to the process implementing the `Socket` as needed. ## `plug_id` the ID of an `Plug` Determines whether or not the socket has an embedded plug. # Returns TRUE if a plug is embedded in the socket An AtkStateSet is a read-only representation of the full set of `AtkStates` that apply to an object at a given time. This set is not meant to be modified, but rather created when `AtkObjectExt::ref_state_set`() is called. # Implements [`StateSetExt`](trait.StateSetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `StateSet` methods. # Implementors [`StateSet`](struct.StateSet.html) Creates a new empty state set. # Returns a new `StateSet` Adds the state of the specified type to the state set if it is not already present. Note that because an `StateSet` is a read-only object, this method should be used to add a state to a newly-created set which will then be returned by `AtkObjectExt::ref_state_set`. It should not be used to modify the existing state of an object. See also `AtkObjectExt::notify_state_change`. ## `type_` an `StateType` # Returns `true` if the state for `type_` is not already in `self`. Adds the states of the specified types to the state set. Note that because an `StateSet` is a read-only object, this method should be used to add states to a newly-created set which will then be returned by `AtkObjectExt::ref_state_set`. It should not be used to modify the existing state of an object. See also `AtkObjectExt::notify_state_change`. ## `types` an array of `StateType` ## `n_types` The number of elements in the array Constructs the intersection of the two sets, returning `None` if the intersection is empty. ## `compare_set` another `StateSet` # Returns a new `StateSet` which is the intersection of the two sets. Removes all states from the state set. Checks whether the state for the specified type is in the specified set. ## `type_` an `StateType` # Returns `true` if `type_` is the state type is in `self`. Checks whether the states for all the specified types are in the specified set. ## `types` an array of `StateType` ## `n_types` The number of elements in the array # Returns `true` if all the states for `type_` are in `self`. Checks whether the state set is empty, i.e. has no states set. # Returns `true` if `self` has no states set, otherwise `false` Constructs the union of the two sets. ## `compare_set` another `StateSet` # Returns a new `StateSet` which is the union of the two sets, returning `None` is empty. Removes the state for the specified type from the state set. Note that because an `StateSet` is a read-only object, this method should be used to remove a state to a newly-created set which will then be returned by `AtkObjectExt::ref_state_set`. It should not be used to modify the existing state of an object. See also `AtkObjectExt::notify_state_change`. ## `type_` an `AtkType` # Returns `true` if `type_` was the state type is in `self`. Constructs the exclusive-or of the two sets, returning `None` is empty. The set returned by this operation contains the states in exactly one of the two sets. ## `compare_set` another `StateSet` # Returns a new `StateSet` which contains the states which are in exactly one of the two sets. The possible types of states of an object Indicates an invalid state - probably an error condition. Indicates a window is currently the active window, or an object is the active subelement within a container or table. ATK_STATE_ACTIVE should not be used for objects which have ATK_STATE_FOCUSABLE or ATK_STATE_SELECTABLE: Those objects should use ATK_STATE_FOCUSED and ATK_STATE_SELECTED respectively. ATK_STATE_ACTIVE is a means to indicate that an object which is not focusable and not selectable is the currently-active item within its parent container. Indicates that the object is 'armed', i.e. will be activated by if a pointer button-release event occurs within its bounds. Buttons often enter this state when a pointer click occurs within their bounds, as a precursor to activation. ATK_STATE_ARMED has been deprecated since ATK-2.16 and should not be used in newly-written code. Indicates the current object is busy, i.e. onscreen representation is in the process of changing, or the object is temporarily unavailable for interaction due to activity already in progress. This state may be used by implementors of Document to indicate that content loading is underway. It also may indicate other 'pending' conditions; clients may wish to interrogate this object when the ATK_STATE_BUSY flag is removed. Indicates this object is currently checked, for instance a checkbox is 'non-empty'. Indicates that this object no longer has a valid backing widget (for instance, if its peer object has been destroyed) Indicates that this object can contain text, and that the user can change the textual contents of this object by editing those contents directly. For an object which is expected to be editable due to its type, but which cannot be edited due to the application or platform preventing the user from doing so, that object's `StateSet` should lack ATK_STATE_EDITABLE and should contain ATK_STATE_READ_ONLY. Indicates that this object is enabled, i.e. that it currently reflects some application state. Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user interaction cannot cause them to acquire STATE_ENABLED. See also: ATK_STATE_SENSITIVE Indicates this object allows progressive disclosure of its children Indicates this object its expanded - see ATK_STATE_EXPANDABLE above Indicates this object can accept keyboard focus, which means all events resulting from typing on the keyboard will normally be passed to it when it has focus Indicates this object currently has the keyboard focus Indicates the orientation of this object is horizontal; used, for instance, by objects of ATK_ROLE_SCROLL_BAR. For objects where vertical/horizontal orientation is especially meaningful. Indicates this object is minimized and is represented only by an icon Indicates something must be done with this object before the user can interact with an object in a different window Indicates this (text) object can contain multiple lines of text Indicates this object allows more than one of its children to be selected at the same time, or in the case of text objects, that the object supports non-contiguous text selections. Indicates this object paints every pixel within its rectangular region. Indicates this object is currently pressed. Indicates the size of this object is not fixed Indicates this object is the child of an object that allows its children to be selected and that this child is one of those children that can be selected Indicates this object is the child of an object that allows its children to be selected and that this child is one of those children that has been selected Indicates this object is sensitive, e.g. to user interaction. STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls, but may be found in the absence of STATE_ENABLED if the current visible state of the control is "disconnected" from the application state. In such cases, direct user interaction can often result in the object gaining STATE_SENSITIVE, for instance if a user makes an explicit selection using an object whose current state is ambiguous or undefined. `see` STATE_ENABLED, STATE_INDETERMINATE. Indicates this object, the object's parent, the object's parent's parent, and so on, are all 'shown' to the end-user, i.e. subject to "exposure" if blocking or obscuring objects do not interpose between this object and the top of the window stack. Indicates this (text) object can contain only a single line of text Indicates that the information returned for this object may no longer be synchronized with the application state. This is implied if the object has STATE_TRANSIENT, and can also occur towards the end of the object peer's lifecycle. It can also be used to indicate that the index associated with this object has changed since the user accessed the object (in lieu of "index-in-parent-changed" events). Indicates this object is transient, i.e. a snapshot which may not emit events when its state changes. Data from objects with ATK_STATE_TRANSIENT should not be cached, since there may be no notification given when the cached data becomes obsolete. Indicates the orientation of this object is vertical Indicates this object is visible, e.g. has been explicitly marked for exposure to the user. Indicates that "active-descendant-changed" event is sent when children become 'active' (i.e. are selected or navigated to onscreen). Used to prevent need to enumerate all children in very large containers, like tables. The presence of STATE_MANAGES_DESCENDANTS is an indication to the client. that the children should not, and need not, be enumerated by the client. Objects implementing this state are expected to provide relevant state notifications to listening clients, for instance notifications of visibility changes and activation of their contained child objects, without the client having previously requested references to those children. Indicates that the value, or some other quantifiable property, of this AtkObject cannot be fully determined. In the case of a large data set in which the total number of items in that set is unknown (e.g. 1 of 999+), implementors should expose the currently-known set size (999) along with this state. In the case of a check box, this state should be used to indicate that the check box is a tri-state check box which is currently neither checked nor unchecked. Indicates that an object is truncated, e.g. a text value in a speradsheet cell. Indicates that explicit user interaction with an object is required by the user interface, e.g. a required field in a "web-form" interface. Indicates that the object has encountered an error condition due to failure of input validation. For instance, a form control may acquire this state in response to invalid or malformed user input. Indicates that the object in question implements some form of ¨typeahead¨ or pre-selection behavior whereby entering the first character of one or more sub-elements causes those elements to scroll into view or become selected. Subsequent character input may narrow the selection further as long as one or more sub-elements match the string. This state is normally only useful and encountered on objects that implement Selection. In some cases the typeahead behavior may result in full or partial ¨completion¨ of the data in the input field, in which case these input events may trigger text-changed events from the AtkText interface. This state supplants `Role::Autocomplete`. Indicates that the object in question supports text selection. It should only be exposed on objects which implement the Text interface, in order to distinguish this state from `StateType::Selectable`, which infers that the object in question is a selectable child of an object which implements Selection. While similar, text selection and subelement selection are distinct operations. Indicates that the object is the "default" active component, i.e. the object which is activated by an end-user press of the "Enter" or "Return" key. Typically a "close" or "submit" button. Indicates that the object changes its appearance dynamically as an inherent part of its presentation. This state may come and go if an object is only temporarily animated on the way to a 'final' onscreen presentation. `note` some applications, notably content viewers, may not be able to detect all kinds of animated content. Therefore the absence of this state should not be taken as definitive evidence that the object's visual representation is static; this state is advisory. Indicates that the object (typically a hyperlink) has already been 'activated', and/or its backing data has already been downloaded, rendered, or otherwise "visited". Indicates this object has the potential to be checked, such as a checkbox or toggle-able table cell. `Since`: ATK-2.12 Indicates that the object has a popup context menu or sub-level menu which may or may not be showing. This means that activation renders conditional content. Note that ordinary tooltips are not considered popups in this context. `Since`: ATK-2.12 Indicates this object has a tooltip. `Since`: ATK-2.16 Indicates that a widget which is ENABLED and SENSITIVE has a value which can be read, but not modified, by the user. Note that this state should only be applied to widget types whose value is normally directly user modifiable, such as check boxes, radio buttons, spin buttons, text input fields, and combo boxes, as a means to convey that the expected interaction with that widget is not possible. When the expected interaction with a widget does not include modification by the user, as is the case with labels and containers, ATK_STATE_READ_ONLY should not be applied. See also ATK_STATE_EDITABLE. `Since`: ATK-2-16 Not a valid state, used for finding end of enumeration An interface whereby an object allows its backing content to be streamed to clients. Typical implementors would be images or icons, HTML content, or multimedia display/rendering widgets. Negotiation of content type is allowed. Clients may examine the backing data and transform, convert, or parse the content in order to present it in an alternate form to end-users. The AtkStreamableContent interface is particularly useful for saving, printing, or post-processing entire documents, or for persisting alternate views of a document. If document content itself is being serialized, stored, or converted, then use of the AtkStreamableContent interface can help address performance issues. Unlike most ATK interfaces, this interface is not strongly tied to the current user-agent view of the a particular document, but may in some cases give access to the underlying model data. # Implements [`StreamableContentExt`](trait.StreamableContentExt.html) Trait containing all `StreamableContent` methods. # Implementors [`StreamableContent`](struct.StreamableContent.html) Gets the character string of the specified mime type. The first mime type is at position 0, the second at position 1, and so on. ## `i` a gint representing the position of the mime type starting from 0 # Returns a gchar* representing the specified mime type; the caller should not free the character string. Gets the number of mime types supported by this object. # Returns a gint which is the number of mime types supported by the object. Gets the content in the specified mime type. ## `mime_type` a gchar* representing the mime type # Returns A `glib::IOChannel` which contains the content in the specified mime type. Get a string representing a URI in IETF standard format (see http://www.ietf.org/rfc/rfc2396.txt) from which the object's content may be streamed in the specified mime-type, if one is available. If mime_type is NULL, the URI for the default (and possibly only) mime-type is returned. Note that it is possible for get_uri to return NULL but for get_stream to work nonetheless, since not all GIOChannels connect to URIs. ## `mime_type` a gchar* representing the mime type, or NULL to request a URI for the default mime type. # Returns Returns a string representing a URI, or `None` if no corresponding URI can be constructed. `Table` should be implemented by components which present elements ordered via rows and columns. It may also be used to present tree-structured information if the nodes of the trees can be said to contain multiple "columns". Individual elements of an `Table` are typically referred to as "cells". Those cells should implement the interface `TableCell`, but `Atk` doesn't require them to be direct children of the current `Table`. They can be grand-children, grand-grand-children etc. `Table` provides the API needed to get a individual cell based on the row and column numbers. Children of `Table` are frequently "lightweight" objects, that is, they may not have backing widgets in the host UI toolkit. They are therefore often transient. Since tables are often very complex, `Table` includes provision for offering simplified summary information, as well as row and column headers and captions. Headers and captions are `AtkObjects` which may implement other interfaces (`Text`, `Image`, etc.) as appropriate. `Table` summaries may themselves be (simplified) `AtkTables`, etc. Note for implementors: in the past, `Table` required that all the cells should be direct children of `Table`, and provided some index based methods to request the cells. The practice showed that that forcing made `Table` implementation complex, and hard to expose other kind of children, like rows or captions. Right now, index-based methods are deprecated. # Implements [`TableExt`](trait.TableExt.html) Trait containing all `Table` methods. # Implementors [`NoOpObject`](struct.NoOpObject.html), [`Table`](struct.Table.html) Adds the specified `column` to the selection. ## `column` a `gint` representing a column in `self` # Returns a gboolean representing if the column was successfully added to the selection, or 0 if value does not implement this interface. Adds the specified `row` to the selection. ## `row` a `gint` representing a row in `self` # Returns a gboolean representing if row was successfully added to selection, or 0 if value does not implement this interface. Gets the caption for the `self`. # Returns a AtkObject* representing the table caption, or `None` if value does not implement this interface. Gets a `gint` representing the column at the specified `index_`. # Deprecated Since 2.12. ## `index_` a `gint` representing an index in `self` # Returns a gint representing the column at the specified index, or -1 if the table does not implement this method. Gets the description text of the specified `column` in the table ## `column` a `gint` representing a column in `self` # Returns a gchar* representing the column description, or `None` if value does not implement this interface. Gets the number of columns occupied by the accessible object at the specified `row` and `column` in the `self`. ## `row` a `gint` representing a row in `self` ## `column` a `gint` representing a column in `self` # Returns a gint representing the column extent at specified position, or 0 if value does not implement this interface. Gets the column header of a specified column in an accessible table. ## `column` a `gint` representing a column in the table # Returns a AtkObject* representing the specified column header, or `None` if value does not implement this interface. Gets a `gint` representing the index at the specified `row` and `column`. # Deprecated Since 2.12. Use `Table::ref_at` in order to get the accessible that represents the cell at (`row`, `column`) ## `row` a `gint` representing a row in `self` ## `column` a `gint` representing a column in `self` # Returns a `gint` representing the index at specified position. The value -1 is returned if the object at row,column is not a child of table or table does not implement this interface. Gets the number of columns in the table. # Returns a gint representing the number of columns, or 0 if value does not implement this interface. Gets the number of rows in the table. # Returns a gint representing the number of rows, or 0 if value does not implement this interface. Gets a `gint` representing the row at the specified `index_`. # Deprecated since 2.12. ## `index_` a `gint` representing an index in `self` # Returns a gint representing the row at the specified index, or -1 if the table does not implement this method. Gets the description text of the specified row in the table ## `row` a `gint` representing a row in `self` # Returns a gchar* representing the row description, or `None` if value does not implement this interface. Gets the number of rows occupied by the accessible object at a specified `row` and `column` in the `self`. ## `row` a `gint` representing a row in `self` ## `column` a `gint` representing a column in `self` # Returns a gint representing the row extent at specified position, or 0 if value does not implement this interface. Gets the row header of a specified row in an accessible table. ## `row` a `gint` representing a row in the table # Returns a AtkObject* representing the specified row header, or `None` if value does not implement this interface. Gets the selected columns of the table by initializing **selected with the selected column numbers. This array should be freed by the caller. ## `selected` a `gint`** that is to contain the selected columns numbers # Returns a gint representing the number of selected columns, or `0` if value does not implement this interface. Gets the selected rows of the table by initializing **selected with the selected row numbers. This array should be freed by the caller. ## `selected` a `gint`** that is to contain the selected row numbers # Returns a gint representing the number of selected rows, or zero if value does not implement this interface. Gets the summary description of the table. # Returns a AtkObject* representing a summary description of the table, or zero if value does not implement this interface. Gets a boolean value indicating whether the specified `column` is selected ## `column` a `gint` representing a column in `self` # Returns a gboolean representing if the column is selected, or 0 if value does not implement this interface. Gets a boolean value indicating whether the specified `row` is selected ## `row` a `gint` representing a row in `self` # Returns a gboolean representing if the row is selected, or 0 if value does not implement this interface. Gets a boolean value indicating whether the accessible object at the specified `row` and `column` is selected ## `row` a `gint` representing a row in `self` ## `column` a `gint` representing a column in `self` # Returns a gboolean representing if the cell is selected, or 0 if value does not implement this interface. Get a reference to the table cell at `row`, `column`. This cell should implement the interface `TableCell` ## `row` a `gint` representing a row in `self` ## `column` a `gint` representing a column in `self` # Returns an `Object` representing the referred to accessible Adds the specified `column` to the selection. ## `column` a `gint` representing a column in `self` # Returns a gboolean representing if the column was successfully removed from the selection, or 0 if value does not implement this interface. Removes the specified `row` from the selection. ## `row` a `gint` representing a row in `self` # Returns a gboolean representing if the row was successfully removed from the selection, or 0 if value does not implement this interface. Sets the caption for the table. ## `caption` a `Object` representing the caption to set for `self` Sets the description text for the specified `column` of the `self`. ## `column` a `gint` representing a column in `self` ## `description` a `gchar` representing the description text to set for the specified `column` of the `self` Sets the specified column header to `header`. ## `column` a `gint` representing a column in `self` ## `header` an `Table` Sets the description text for the specified `row` of `self`. ## `row` a `gint` representing a row in `self` ## `description` a `gchar` representing the description text to set for the specified `row` of `self` Sets the specified row header to `header`. ## `row` a `gint` representing a row in `self` ## `header` an `Table` Sets the summary description of the table. ## `accessible` an `Object` representing the summary description to set for `self` The "column-deleted" signal is emitted by an object which implements the AtkTable interface when a column is deleted. ## `arg1` The index of the first column deleted. ## `arg2` The number of columns deleted. The "column-inserted" signal is emitted by an object which implements the AtkTable interface when a column is inserted. ## `arg1` The index of the column inserted. ## `arg2` The number of colums inserted. The "column-reordered" signal is emitted by an object which implements the AtkTable interface when the columns are reordered. The "model-changed" signal is emitted by an object which implements the AtkTable interface when the model displayed by the table changes. The "row-deleted" signal is emitted by an object which implements the AtkTable interface when a row is deleted. ## `arg1` The index of the first row deleted. ## `arg2` The number of rows deleted. The "row-inserted" signal is emitted by an object which implements the AtkTable interface when a row is inserted. ## `arg1` The index of the first row inserted. ## `arg2` The number of rows inserted. The "row-reordered" signal is emitted by an object which implements the AtkTable interface when the rows are reordered. Being `Table` a component which present elements ordered via rows and columns, an `TableCell` is the interface which each of those elements, so "cells" should implement. See also `Table`. # Implements [`TableCellExt`](trait.TableCellExt.html), [`AtkObjectExt`](trait.AtkObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TableCell` methods. # Implementors [`NoOpObject`](struct.NoOpObject.html), [`TableCell`](struct.TableCell.html) Returns the column headers as an array of cell accessibles. # Returns a GPtrArray of AtkObjects representing the column header cells. Returns the number of columns occupied by this cell accessible. # Returns a gint representing the number of columns occupied by this cell, or 0 if the cell does not implement this method. Retrieves the tabular position of this cell. ## `row` the row of the given cell. ## `column` the column of the given cell. # Returns TRUE if successful; FALSE otherwise. Gets the row and column indexes and span of this cell accessible. Note: If the object does not implement this function, then, by default, atk will implement this function by calling get_row_span and get_column_span on the object. ## `row` the row index of the given cell. ## `column` the column index of the given cell. ## `row_span` the number of rows occupied by this cell. ## `column_span` the number of columns occupied by this cell. # Returns TRUE if successful; FALSE otherwise. Returns the row headers as an array of cell accessibles. # Returns a GPtrArray of AtkObjects representing the row header cells. Returns the number of rows occupied by this cell accessible. # Returns a gint representing the number of rows occupied by this cell, or 0 if the cell does not implement this method. Returns a reference to the accessible of the containing table. # Returns the atk object for the containing table. `Text` should be implemented by `AtkObjects` on behalf of widgets that have text content which is either attributed or otherwise non-trivial. `AtkObjects` whose text content is simple, unattributed, and very brief may expose that content via `AtkObjectExt::get_name` instead; however if the text is editable, multi-line, typically longer than three or four words, attributed, selectable, or if the object already uses the 'name' ATK property for other information, the `Text` interface should be used to expose the text content. In the case of editable text content, `EditableText` (a subtype of the `Text` interface) should be implemented instead. `Text` provides not only traversal facilities and change notification for text content, but also caret tracking and glyph bounding box calculations. Note that the text strings are exposed as UTF-8, and are therefore potentially multi-byte, and caret-to-byte offset mapping makes no assumptions about the character length; also bounding box glyph-to-offset mapping may be complex for languages which use ligatures. # Implements [`TextExt`](trait.TextExt.html) Trait containing all `Text` methods. # Implementors [`NoOpObject`](struct.NoOpObject.html), [`Text`](struct.Text.html) Frees the memory associated with an array of AtkTextRange. It is assumed that the array was returned by the function atk_text_get_bounded_ranges and is NULL terminated. ## `ranges` A pointer to an array of `TextRange` which is to be freed. Adds a selection bounded by the specified offsets. ## `start_offset` the starting character offset of the selected region ## `end_offset` the offset of the first character after the selected region. # Returns `true` if success, `false` otherwise Get the ranges of text in the specified bounding box. ## `rect` An AtkTextRectangle giving the dimensions of the bounding box. ## `coord_type` Specify whether coordinates are relative to the screen or widget window. ## `x_clip_type` Specify the horizontal clip type. ## `y_clip_type` Specify the vertical clip type. # Returns Array of AtkTextRange. The last element of the array returned by this function will be NULL. Gets the offset of the position of the caret (cursor). # Returns the character offset of position of the caret (cursor). Gets the specified text. ## `offset` a character offset within `self` # Returns the character at `offset`. Gets the character count. # Returns the number of characters. Get the bounding box containing the glyph representing the character at a particular text offset. ## `offset` The offset of the text character for which bounding information is required. ## `x` Pointer for the x coordinate of the bounding box ## `y` Pointer for the y coordinate of the bounding box ## `width` Pointer for the width of the bounding box ## `height` Pointer for the height of the bounding box ## `coords` specify whether coordinates are relative to the screen or widget window Creates an `AttributeSet` which consists of the default values of attributes for the text. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned. # Returns an `AttributeSet` which contains the default values of attributes. at `offset`. this `atkattributeset` should be freed by a call to `Attribute::set_free`. Gets the number of selected regions. # Returns The number of selected regions, or -1 if a failure occurred. Gets the offset of the character located at coordinates `x` and `y`. `x` and `y` are interpreted as being relative to the screen or this widget's window depending on `coords`. ## `x` screen x-position of character ## `y` screen y-position of character ## `coords` specify whether coordinates are relative to the screen or widget window # Returns the offset to the character which is located at the specified `x` and `y` coordinates. Get the bounding box for text within the specified range. ## `start_offset` The offset of the first text character for which boundary information is required. ## `end_offset` The offset of the text character after the last character for which boundary information is required. ## `coord_type` Specify whether coordinates are relative to the screen or widget window. ## `rect` A pointer to a AtkTextRectangle which is filled in by this function. Creates an `AttributeSet` which consists of the attributes explicitly set at the position `offset` in the text. `start_offset` and `end_offset` are set to the start and end of the range around `offset` where the attributes are invariant. Note that `end_offset` is the offset of the first character after the range. See the enum AtkTextAttribute for types of text attributes that can be returned. Note that other attributes may also be returned. ## `offset` the character offset at which to get the attributes, -1 means the offset of the character to be inserted at the caret location. ## `start_offset` the address to put the start offset of the range ## `end_offset` the address to put the end offset of the range # Returns an `AttributeSet` which contains the attributes explicitly set at `offset`. This `AttributeSet` should be freed by a call to `Attribute::set_free`. Gets the text from the specified selection. ## `selection_num` The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. ## `start_offset` passes back the starting character offset of the selected region ## `end_offset` passes back the ending character offset (offset immediately past) of the selected region # Returns a newly allocated string containing the selected text. Use `g_free` to free the returned string. Gets a portion of the text exposed through an `Text` according to a given `offset` and a specific `granularity`, along with the start and end offsets defining the boundaries of such a portion of text. If `granularity` is ATK_TEXT_GRANULARITY_CHAR the character at the offset is returned. If `granularity` is ATK_TEXT_GRANULARITY_WORD the returned string is from the word start at or before the offset to the word start after the offset. The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word. If `granularity` is ATK_TEXT_GRANULARITY_SENTENCE the returned string is from the sentence start at or before the offset to the sentence start after the offset. The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence. If `granularity` is ATK_TEXT_GRANULARITY_LINE the returned string is from the line start at or before the offset to the line start after the offset. If `granularity` is ATK_TEXT_GRANULARITY_PARAGRAPH the returned string is from the start of the paragraph at or before the offset to the start of the following paragraph after the offset. ## `offset` position ## `granularity` An `TextGranularity` ## `start_offset` the starting character offset of the returned string, or -1 if an error has occurred (e.g. invalid offset, not implemented) ## `end_offset` the offset of the first character after the returned string, or -1 if an error has occurred (e.g. invalid offset, not implemented) # Returns a newly allocated string containing the text at the `offset` bounded by the specified `granularity`. Use `g_free` to free the returned string. Returns `None` if the offset is invalid or no implementation is available. Gets the specified text. ## `start_offset` a starting character offset within `self` ## `end_offset` an ending character offset within `self`, or -1 for the end of the string. # Returns a newly allocated string containing the text from `start_offset` up to, but not including `end_offset`. Use `g_free` to free the returned string. Gets the specified text. If the boundary_type if ATK_TEXT_BOUNDARY_CHAR the character at the offset is returned. If the boundary_type is ATK_TEXT_BOUNDARY_WORD_START the returned string is from the word start at or before the offset to the word start after the offset. The returned string will contain the word at the offset if the offset is inside a word and will contain the word before the offset if the offset is not inside a word. If the boundary type is ATK_TEXT_BOUNDARY_SENTENCE_START the returned string is from the sentence start at or before the offset to the sentence start after the offset. The returned string will contain the sentence at the offset if the offset is inside a sentence and will contain the sentence before the offset if the offset is not inside a sentence. If the boundary type is ATK_TEXT_BOUNDARY_LINE_START the returned string is from the line start at or before the offset to the line start after the offset. # Deprecated This method is deprecated since ATK version 2.9.4. Please use `Text::get_string_at_offset` instead. ## `offset` position ## `boundary_type` An `TextBoundary` ## `start_offset` the starting character offset of the returned string ## `end_offset` the offset of the first character after the returned substring # Returns a newly allocated string containing the text at `offset` bounded by the specified `boundary_type`. Use `g_free` to free the returned string. Removes the specified selection. ## `selection_num` The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. # Returns `true` if success, `false` otherwise Sets the caret (cursor) position to the specified `offset`. ## `offset` the character offset of the new caret position # Returns `true` if success, `false` otherwise. Changes the start and end offset of the specified selection. ## `selection_num` The selection number. The selected regions are assigned numbers that correspond to how far the region is from the start of the text. The selected region closest to the beginning of the text region is assigned the number 0, etc. Note that adding, moving or deleting a selected region can change the numbering. ## `start_offset` the new starting character offset of the selection ## `end_offset` the new end position of (e.g. offset immediately past) the selection # Returns `true` if success, `false` otherwise The "text-attributes-changed" signal is emitted when the text attributes of the text of an object which implements AtkText changes. The "text-caret-moved" signal is emitted when the caret position of the text of an object which implements AtkText changes. ## `arg1` The new position of the text caret. The "text-insert" signal is emitted when a new text is inserted. If the signal was not triggered by the user (e.g. typing or pasting text), the "system" detail should be included. ## `arg1` The position (character offset) of the insertion. ## `arg2` The length (in characters) of text inserted. ## `arg3` The new text inserted The "text-remove" signal is emitted when a new text is removed. If the signal was not triggered by the user (e.g. typing or pasting text), the "system" detail should be included. ## `arg1` The position (character offset) of the removal. ## `arg2` The length (in characters) of text removed. ## `arg3` The old text removed The "text-selection-changed" signal is emitted when the selected text of an object which implements AtkText changes. Describes the text attributes supported Invalid attribute, like bad spelling or grammar. The pixel width of the left margin The pixel width of the right margin The number of pixels that the text is indented Either "true" or "false" indicating whether text is visible or not Either "true" or "false" indicating whether text is editable or not Pixels of blank space to leave above each newline-terminated line. Pixels of blank space to leave below each newline-terminated line. Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph). "true" or "false" whether to make the background color for each character the height of the highest font used on the current line, or the height of the font used for the current character. Number of pixels that the characters are risen above the baseline "none", "single", "double", "low", or "error" "true" or "false" whether the text is strikethrough The size of the characters in points. eg: 10 The scale of the characters. The value is a string representation of a double The weight of the characters. The language used The font family name The background color. The value is an RGB value of the format "`u`,`u`,`u`" The foreground color. The value is an RGB value of the format "`u`,`u`,`u`" "true" if a ``GdkBitmap`` is set for stippling the background color. "true" if a ``GdkBitmap`` is set for stippling the foreground color. The wrap mode of the text, if any. Values are "none", "char", "word", or "word_char". The direction of the text, if set. Values are "none", "ltr" or "rtl" The justification of the text, if set. Values are "left", "right", "center" or "fill" The stretch of the text, if set. Values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" or "ultra_expanded" The capitalization variant of the text, if set. Values are "normal" or "small_caps" The slant style of the text, if set. Values are "normal", "oblique" or "italic" not a valid text attribute, used for finding end of enumeration Text boundary types used for specifying boundaries for regions of text. This enumeration is deprecated since 2.9.4 and should not be used. Use AtkTextGranularity with `Text::get_string_at_offset` instead. Boundary is the boundary between characters (including non-printing characters) Boundary is the start (i.e. first character) of a word. Boundary is the end (i.e. last character) of a word. Boundary is the first character in a sentence. Boundary is the last (terminal) character in a sentence; in languages which use "sentence stop" punctuation such as English, the boundary is thus the '.', '?', or similar terminal punctuation character. Boundary is the initial character of the content or a character immediately following a newline, linefeed, or return character. Boundary is the linefeed, or return character. Describes the type of clipping required. No clipping to be done Text clipped by min coordinate is omitted Text clipped by max coordinate is omitted Only text fully within mix/max bound is retained Text granularity types used for specifying the granularity of the region of text we are interested in. Granularity is defined by the boundaries between characters (including non-printing characters) Granularity is defined by the boundaries of a word, starting at the beginning of the current word and finishing at the beginning of the following one, if present. Granularity is defined by the boundaries of a sentence, starting at the beginning of the current sentence and finishing at the beginning of the following one, if present. Granularity is defined by the boundaries of a line, starting at the beginning of the current line and finishing at the beginning of the following one, if present. Granularity is defined by the boundaries of a paragraph, starting at the beginning of the current paragraph and finishing at the beginning of the following one, if present. A structure used to describe a text range. A structure used to store a rectangle used by AtkText. A set of ATK utility functions which are used to support event registration of various types, and obtaining the 'root' accessible of a process and information about the current ATK implementation and toolkit version. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) `Value` should be implemented for components which either display a value from a bounded range, or which allow the user to specify a value from a bounded range, or both. For instance, most sliders and range controls, as well as dials, should have `Object` representations which implement `Value` on the component's behalf. `AtKValues` may be read-only, in which case attempts to alter the value return would fail. ``On the subject of current value text`` `` In addition to providing the current value, implementors can optionally provide an end-user-consumable textual description associated with this value. This description should be included when the numeric value fails to convey the full, on-screen representation seen by users. `` `` ``Password strength`` A password strength meter whose value changes as the user types their new password. Red is used for values less than 4.0, yellow for values between 4.0 and 7.0, and green for values greater than 7.0. In this instance, value text should be provided by the implementor. Appropriate value text would be "weak", "acceptable," and "strong" respectively. `` A level bar whose value changes to reflect the battery charge. The color remains the same regardless of the charge and there is no on-screen text reflecting the fullness of the battery. In this case, because the position within the bar is the only indication the user has of the current charge, value text should not be provided by the implementor. ``Implementor Notes`` `` Implementors should bear in mind that assistive technologies will likely prefer the value text provided over the numeric value when presenting a widget's value. As a result, strings not intended for end users should not be exposed in the value text, and strings which are exposed should be localized. In the case of widgets which display value text on screen, for instance through a separate label in close proximity to the value-displaying widget, it is still expected that implementors will expose the value text using the above API. `` `` `Value` should NOT be implemented for widgets whose displayed value is not reflective of a meaningful amount. For instance, a progress pulse indicator whose value alternates between 0.0 and 1.0 to indicate that some process is still taking place should not implement `Value` because the current value does not reflect progress towards completion. `` `` `` ``On the subject of ranges`` `` In addition to providing the minimum and maximum values, implementors can optionally provide details about subranges associated with the widget. These details should be provided by the implementor when both of the following are communicated visually to the end user: `` `` ``The existence of distinct ranges such as "weak", "acceptable", and "strong" indicated by color, bar tick marks, and/or on-screen text.`` ``Where the current value stands within a given subrange, for instance illustrating progression from very "weak" towards nearly "acceptable" through changes in shade and/or position on the bar within the "weak" subrange.`` `` `` If both of the above do not apply to the widget, it should be sufficient to expose the numeric value, along with the value text if appropriate, to make the widget accessible. `` ``Implementor Notes`` `` If providing subrange details is deemed necessary, all possible values of the widget are expected to fall within one of the subranges defined by the implementor. `` `` `` ``On the subject of localization of end-user-consumable text values`` `` Because value text and subrange descriptors are human-consumable, implementors are expected to provide localized strings which can be directly presented to end users via their assistive technology. In order to simplify this for implementors, implementors can use `ValueType::get_localized_name` with the following already-localized constants for commonly-needed values can be used: `` `` ``ATK_VALUE_VERY_WEAK`` ``ATK_VALUE_WEAK`` ``ATK_VALUE_ACCEPTABLE`` ``ATK_VALUE_STRONG`` ``ATK_VALUE_VERY_STRONG`` ``ATK_VALUE_VERY_LOW`` ``ATK_VALUE_LOW`` ``ATK_VALUE_MEDIUM`` ``ATK_VALUE_HIGH`` ``ATK_VALUE_VERY_HIGH`` ``ATK_VALUE_VERY_BAD`` ``ATK_VALUE_BAD`` ``ATK_VALUE_GOOD`` ``ATK_VALUE_VERY_GOOD`` ``ATK_VALUE_BEST`` ``ATK_VALUE_SUBSUBOPTIMAL`` ``ATK_VALUE_SUBOPTIMAL`` ``ATK_VALUE_OPTIMAL`` `` `` Proposals for additional constants, along with their use cases, should be submitted to the GNOME Accessibility Team. `` `` ``On the subject of changes`` `` Note that if there is a textual description associated with the new numeric value, that description should be included regardless of whether or not it has also changed. `` `` # Implements [`ValueExt`](trait.ValueExt.html) Trait containing all `Value` methods. # Implementors [`NoOpObject`](struct.NoOpObject.html), [`Value`](struct.Value.html) Gets the value of this object. # Deprecated Since 2.12. Use `Value::get_value_and_text` instead. ## `value` a `gobject::Value` representing the current accessible value Gets the minimum increment by which the value of this object may be changed. If zero, the minimum increment is undefined, which may mean that it is limited only by the floating point precision of the platform. # Returns the minimum increment by which the value of this object may be changed. zero if undefined. Gets the maximum value of this object. # Deprecated Since 2.12. Use `Value::get_range` instead. ## `value` a `gobject::Value` representing the maximum accessible value Gets the minimum increment by which the value of this object may be changed. If zero, the minimum increment is undefined, which may mean that it is limited only by the floating point precision of the platform. # Deprecated Since 2.12. Use `Value::get_increment` instead. ## `value` a `gobject::Value` representing the minimum increment by which the accessible value may be changed Gets the minimum value of this object. # Deprecated Since 2.12. Use `Value::get_range` instead. ## `value` a `gobject::Value` representing the minimum accessible value Gets the range of this object. # Returns a newly allocated `Range` that represents the minimum, maximum and descriptor (if available) of `self`. NULL if that range is not defined. Gets the list of subranges defined for this object. See `Value` introduction for examples of subranges and when to expose them. # Returns an `glib::SList` of `Range` which each of the subranges defined for this object. Free the returns list with `glib::SList::free`. Gets the current value and the human readable text alternative of `self`. `text` is a newly created string, that must be freed by the caller. Can be NULL if no descriptor is available. ## `value` address of `gdouble` to put the current value of `self` ## `text` address of `gchar` to put the human readable text alternative for `value` Sets the value of this object. # Deprecated Since 2.12. Use `Value::set_value` instead. ## `value` a `gobject::Value` which is the desired new accessible value. # Returns `true` if new value is successfully set, `false` otherwise. Sets the value of this object. This method is intended to provide a way to change the value of the object. In any case, it is possible that the value can't be modified (ie: a read-only component). If the value changes due this call, it is possible that the text could change, and will trigger an `Value::value-changed` signal emission. Note for implementors: the deprecated `Value::set_current_value` method returned TRUE or FALSE depending if the value was assigned or not. In the practice several implementors were not able to decide it, and returned TRUE in any case. For that reason it is not required anymore to return if the value was properly assigned or not. ## `new_value` a double which is the desired new accessible value. The 'value-changed' signal is emitted when the current value that represent the object changes. `value` is the numerical representation of this new value. `text` is the human readable text alternative of `value`, and can be NULL if it is not available. Note that if there is a textual description associated with the new numeric value, that description should be included regardless of whether or not it has also changed. Example: a password meter whose value changes as the user types their new password. Appropiate value text would be "weak", "acceptable" and "strong". ## `value` the new value in a numerical form. ## `text` human readable text alternative (also called description) of this object. NULL if not available. Default types for a given value. Those are defined in order to easily get localized strings to describe a given value or a given subrange, using `ValueType::get_localized_name`. `Window` should be implemented by the UI elements that represent a top-level window, such as the main window of an application or dialog. # Implements [`AtkWindowExt`](trait.AtkWindowExt.html), [`AtkObjectExt`](trait.AtkObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Window` methods. # Implementors [`NoOpObject`](struct.NoOpObject.html), [`Window`](struct.Window.html) The signal `Window::activate` is emitted when a window becomes the active window of the application or session. The signal `Window::create` is emitted when a new window is created. The signal `Window::deactivate` is emitted when a window is no longer the active window of the application or session. The signal `Window::destroy` is emitted when a window is destroyed. The signal `Window::maximize` is emitted when a window is maximized. The signal `Window::minimize` is emitted when a window is minimized. The signal `Window::move` is emitted when a window is moved. The signal `Window::resize` is emitted when a window is resized. The signal `Window::restore` is emitted when a window is restored. gtk-rs-lgpl-docs-0.1.12/cairo/docs.md010064400007650000024000002732631350370316500154720ustar0000000000000000 Status is used to indicate errors that can occur when using Cairo. In some cases it is returned directly by functions, but when using `Context`, the last error, if any, is stored in the context and can be retrieved with `Context::status()`. New entries may be added in future versions. Use `Context::status_to_string()` to get a human-readable representation of an error message. no error has occurred (Since 1.0) out of memory (Since 1.0) `Context::restore()` called without matching `Context::save()` (Since 1.0) no saved group to pop, i.e. `Context::pop_group()` without matching `Context::push_group()` (Since 1.0) no current point defined (Since 1.0) invalid matrix (not invertible) (Since 1.0) invalid value for an input `Status` (Since 1.0) NULL pointer (Since 1.0) input string not valid UTF-8 (Since 1.0) input path data not valid (Since 1.0) error while reading from input stream (Since 1.0) error while writing to output stream (Since 1.0) target surface has been finished (Since 1.0) the surface type is not appropriate for the operation (Since 1.0) the pattern type is not appropriate for the operation (Since 1.0) invalid value for an input `Content` (Since 1.0) invalid value for an input `Format` (Since 1.0) invalid value for an input Visual* (Since 1.0) file not found (Since 1.0) invalid value for a dash setting (Since 1.0) invalid value for a DSC comment (Since 1.2) invalid index passed to getter (Since 1.4) clip region not representable in desired format (Since 1.4) error creating or writing to a temporary file (Since 1.6) invalid value for stride (Since 1.6) the font type is not appropriate for the operation (Since 1.8) the user-font is immutable (Since 1.8) error occurred in a user-font callback function (Since 1.8) negative number used where it is not allowed (Since 1.8) input clusters do not represent the accompanying text and glyph array (Since 1.8) invalid value for an input `FontSlant` (Since 1.8) invalid value for an input `FontWeight` (Since 1.8) invalid value (typically too big) for the size of the input (surface, pattern, etc.) (Since 1.10) user-font method not implemented (Since 1.10) the device type is not appropriate for the operation (Since 1.10) an operation to the device caused an unspecified error (Since 1.10) a mesh pattern construction operation was used outside of a `Context::mesh_pattern_begin_patch()`/`Context::mesh_pattern_end_patch()` pair (Since 1.12) target device has been finished (Since 1.12) this is a special value indicating the number of status values defined in this enumeration. When using this value, note that the version of cairo at run-time may have additional status values defined than the value of this symbol at compile-time. (Since 1.10) Specifies the type of antialiasing to do when rendering text or shapes. As it is not necessarily clear from the above what advantages a particular antialias method provides, since 1.12, there is also a set of hints: `Fast`: Allow the backend to degrade raster quality for speed. `Good`: A balance between speed and quality. `Best`: A high-fidelity, but potentially slow, raster mode. These make no guarantee on how the backend will perform its rasterisation (if it even rasterises!), nor that they have any differing effect other than to enable some form of antialiasing. In the case of glyph rendering, `Fast` and `Good` will be mapped to `Gray`, with `Best` being equivalent to `Subpixel`. The interpretation of `Default` is left entirely up to the backend, typically this will be similar to `Good`. Use the default antialiasing for the subsystem and target device, since 1.0 Use a bilevel alpha mask, since 1.0 Perform single-color antialiasing (using shades of gray for black text on a white background, for example), since 1.0 Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels, since 1.0 Hint that the backend should perform some antialiasing but prefer speed over quality, since 1.12 The backend should balance quality against performance, since 1.12 Hint that the backend should render at the highest quality, sacrificing speed if necessary, since 1.12 `FillRule` is used to select how paths are filled. For both fill rules, whether or not a point is included in the fill is determined by taking a ray from that point to infinity and looking at intersections with the path. The ray can be in any direction, as long as it doesn't pass through the end point of a segment or have a tricky intersection such as intersecting tangent to the path. (Note that filling is not actually implemented in this way. This is just a description of the rule that is applied.) The default fill rule is `Winding`. New entries may be added in future versions. If the path crosses the ray from left-to-right, counts +1. If the path crosses the ray from right to left, counts -1. (Left and right are determined from the perspective of looking along the ray from the starting point.) If the total count is non-zero, the point will be filled. (Since 1.0) Counts the total number of intersections, without regard to the orientation of the contour. If the total number of intersections is odd, the point will be filled. (Since 1.0) Specifies how to render the endpoints of the path when stroking. The default line cap style is `Butt`. start(stop) the line exactly at the start(end) point (Since 1.0) use a round ending, the center of the circle is the end point (Since 1.0) use squared ending, the center of the square is the end point (Since 1.0) Specifies how to render the junction of two lines when stroking. The default line join style is `Miter`. use a sharp (angled) corner, see `Context::set_miter_limit()` (Since 1.0) use a rounded join, the center of the circle is the joint point (Since 1.0) use a cut-off join, the join is cut off at half the line width from the joint point (Since 1.0) `Operator` is used to set the compositing operator for all cairo drawing operations. The default operator is `Over`. The operators marked as unbounded modify their destination even outside of the mask layer (that is, their effect is not bound by the mask layer). However, their effect can still be limited by way of clipping. To keep things simple, the operator descriptions here document the behavior for when both source and destination are either fully transparent or fully opaque. The actual implementation works for translucent layers too. For a more detailed explanation of the effects of each operator, including the mathematical definitions, see http:cairographics.org/operators/. clear destination layer (bounded) (Since 1.0) replace destination layer (bounded) (Since 1.0) draw source layer on top of destination layer (bounded) (Since 1.0) draw source where there was destination content (unbounded) (Since 1.0) draw source where there was no destination content (unbounded) (Since 1.0) draw source on top of destination content and only there (Since 1.0) ignore the source (Since 1.0) draw destination on top of source (Since 1.0) leave destination only where there was source content (unbounded) (Since 1.0) leave destination only where there was no source content (Since 1.0) leave destination on top of source content and only there (unbounded) (Since 1.0) source and destination are shown where there is only one of them (Since 1.0) source and destination layers are accumulated (Since 1.0) like over, but assuming source and dest are disjoint geometries (Since 1.0) source and destination layers are multiplied. This causes the result to be at least as dark as the darker inputs. (Since 1.10) source and destination are complemented and multiplied. This causes the result to be at least as light as the lighter inputs. (Since 1.10) multiplies or screens, depending on the lightness of the destination color. (Since 1.10) replaces the destination with the source if it is darker, otherwise keeps the source. (Since 1.10) replaces the destination with the source if it is lighter, otherwise keeps the source. (Since 1.10) brightens the destination color to reflect the source color. (Since 1.10) darkens the destination color to reflect the source color. (Since 1.10) Multiplies or screens, dependent on source color. (Since 1.10) Darkens or lightens, dependent on source color. (Since 1.10) Takes the difference of the source and destination color. (Since 1.10) Produces an effect similar to difference, but with lower contrast. (Since 1.10) Creates a color with the hue of the source and the saturation and luminosity of the target. (Since 1.10) Creates a color with the saturation of the source and the hue and luminosity of the target. Painting with this mode onto a gray area produces no change. (Since 1.10) Creates a color with the hue and saturation of the source and the luminosity of the target. This preserves the gray levels of the target and is useful for coloring monochrome images or tinting color images. (Since 1.10) Creates a color with the luminosity of the source and the hue and saturation of the target. This produces an inverse effect to `HslColor`. (Since 1.10) `PathData` is used to describe the type of one portion of a path when represented as a `Path`. See `PathData` for details. A move-to operation, since 1.0 A line-to operation, since 1.0 A curve-to operation, since 1.0 A close-path operation, since 1.0 `Content` is used to describe the content that a surface will contain, whether color information, alpha information (translucence vs. opacity), or both. Note: The large values here are designed to keep `Content` values distinct from `Format` values so that the implementation can detect the error if users confuse the two types. The surface will hold color content only. (Since 1.0) The surface will hold alpha content only. (Since 1.0) The surface will hold color and alpha content. (Since 1.0) `Extend` is used to describe how pattern color/alpha will be determined for areas "outside" the pattern's natural area, (for example, outside the surface bounds or outside the gradient geometry). Mesh patterns are not affected by the extend mode. The default extend mode is `None` for surface patterns and `Pad` for gradient patterns. New entries may be added in future versions. pixels outside of the source pattern are fully transparent (Since 1.0) the pattern is tiled by repeating (Since 1.0) the pattern is tiled by reflecting at the edges (Since 1.0; but only implemented for surface patterns since 1.6) pixels outside of the pattern copy the closest pixel from the source (Since 1.2; but only implemented for surface patterns since 1.6) `Filter` is used to indicate what filtering should be applied when reading pixel values from patterns. See `Pattern::set_filter()` for indicating the desired filter to be used with a particular pattern. A high-performance filter, with quality similar to `Nearest` (Since 1.0) A reasonable-performance filter, with quality similar to `Bilinear` (Since 1.0) The highest-quality available, performance may not be suitable for interactive use. (Since 1.0) Nearest-neighbor filtering (Since 1.0) Linear interpolation in two dimensions (Since 1.0) This filter value is currently unimplemented, and should not be used in current code. (Since 1.0) `PatternType` is used to describe the type of a given pattern. The type of a pattern is determined by the function used to create it. The `Pattern::create_rgb()` and `Pattern::create_rgba()` functions create `Solid` patterns. The remaining cairo_pattern_create functions map to pattern types in obvious ways. The pattern type can be queried with `Pattern::get_type()`. Most `Pattern` functions can be called with a pattern of any type, (though trying to change the extend or filter for a solid pattern will have no effect). A notable exception is `Pattern::add_color_stop_rgb()` and `Pattern::add_color_stop_rgba()` which must only be called with gradient patterns (either `Linear` or `Radial`). Otherwise the pattern will be shutdown and put into an error state. New entries may be added in future versions. The pattern is a solid (uniform) color. It may be opaque or translucent, since 1.2. The pattern is a based on a surface (an image), since 1.2. The pattern is a linear gradient, since 1.2. The pattern is a radial gradient, since 1.2. The pattern is a mesh, since 1.12. The pattern is a user pattern providing raster data, since 1.12. Specifies variants of a font face based on their slant. Upright font style, since 1.0 Italic font style, since 1.0 Oblique font style, since 1.0 Specifies variants of a font face based on their weight. Normal font weight, since 1.0 Bold font weight, since 1.0 Specifies properties of a text cluster mapping. The clusters in the cluster array map to glyphs in the glyph array from end to start. (Since 1.8) `FontType` is used to describe the type of a given font face or scaled font. The font types are also known as "font backends" within cairo. The type of a font face is determined by the function used to create it, which will generally be of the form `Context::type_font_face_create()`. The font face type can be queried with `Context::font_face_get_type()`. The various cairo_font_face_t functions can be used with a font face of any type. The type of a scaled font is determined by the type of the font face passed to `Context::scaled_font_create()`. The scaled font type can be queried with `Context::scaled_font_get_type()`. The various `ScaledFont` functions can be used with scaled fonts of any type, but some font backends also provide type-specific functions that must only be called with a scaled font of the appropriate type. These functions have names that begin with `Context::type_scaled_font()` such as `Context::ft_scaled_font_lock_face()`. The behavior of calling a type-specific function with a scaled font of the wrong type is undefined. New entries may be added in future versions. The font was created using cairo's toy font api (Feature: `v1_2`) The font is of type FreeType (Feature: `v1_2`) The font is of type Win32 (Feature: `v1_2`) The font is of type Quartz (Feature: `v1_6`, in 1.2 and 1.4 it was named CAIRO_FONT_TYPE_ATSUI) The font was create using cairo's user font api (Feature: `v1_8`) The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of `Antialias::Subpixel`. Use the default subpixel order for for the target device, since 1.0 Subpixel elements are arranged horizontally with red at the left, since 1.0 Subpixel elements are arranged horizontally with blue at the left, since 1.0 Subpixel elements are arranged vertically with red at the top, since 1.0 Subpixel elements are arranged vertically with blue at the top, since 1.0 Specifies the type of hinting to do on font outlines. Hinting is the process of fitting outlines to the pixel grid in order to improve the appearance of the result. Since hinting outlines involves distorting them, it also reduces the faithfulness to the original outline shapes. Not all of the outline hinting styles are supported by all font backends. New entries may be added in future versions. Use the default hint style for font backend and target device, since 1.0 Do not hint outlines, since 1.0 Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes, since 1.0 Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast, since 1.0 Hint outlines to maximize contrast, since 1.0 Specifies whether to hint font metrics; hinting font metrics means quantizing them so that they are integer values in device space. Doing this improves the consistency of letter and line spacing, however it also means that text will be laid out differently at different zoom factors Hint metrics in the default manner for the font backend and target device, since 1.0 Do not hint font metrics, since 1.0 Hint font metrics, since 1.0 The cairo drawing context Creates a new Context with all graphics state parameters set to default values and with target as a target surface. The target surface should be constructed with a backend-specific function such as cairo_image_surface_create() (or any other Context::backend_surface_create() variant). This function references target , so you can immediately call Surface::drop() on it if you don't need to maintain a separate reference to it. Checks whether an error has previously occurred for this context. Makes a copy of the current state of self and saves it on an internal stack of saved states for self. When Context::restore() is called, self will be restored to the saved state. Multiple calls to Context::save() and Context::restore() can be nested; each call to Context::restore() restores the state from the matching paired Context::save(). It isn't necessary to clear all saved states before a Context is freed. If the reference count of a Context drops to zero in response to a call to Context::drop(), any saved states will be freed along with the Context. Restores self to the state saved by a preceding call to Context::save() and removes that state from the stack of saved states. Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to Context::pop_group() or Context::pop_group_to_source(). These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern). This group functionality can be convenient for performing intermediate compositing. One common use of a group is to render objects as opaque within the group, (so that they occlude each other), and then blend the result with translucence onto the destination. Groups can be nested arbitrarily deep by making balanced calls to Context::push_group() / Context::pop_group(). Each call pushes /pops the new target group onto/from a stack. The Context::push_group() function calls Context::save() so that any changes to the graphics state will not be visible outside the group, (the pop_group functions call Context::restore()). By default the intermediate group will have a content type of Content::ColorAlpha. Other content types can be chosen for the group by using Context::push_group_with_content() instead. As an example, here is how one might fill and stroke a path with translucence, but without any portion of the fill being visible under the stroke: ```ignore cr.push_group(); cr.set_source (fill_pattern); cr.fill_preserve(); cr.set_source(); cr.stroke(); cr.pop_group_to_source(); cr.paint_with_alpha(alpha); ``` Terminates the redirection begun by a call to Context::push_group() or Context::push_group_with_content() and returns a new pattern containing the results of all drawing operations performed to the group. The Context::pop_group() function calls Context::restore(), (balancing a call to Context::save() by the push_group function), so that any changes to the graphics state will not be visible outside the group. Terminates the redirection begun by a call to Context::push_group() or Context::push_group_with_content() and installs the resulting pattern as the source pattern in the given cairo context. The behavior of this function is equivalent to the sequence of operations: ```ignore let mut group = context.pop_group(); context.set_source(group); ``` but is more convenient as their is no need for a variable to store the short-lived pointer to the pattern. The Context::pop_group() function calls Context::restore(), (balancing a call to Context::save() by the push_group function), so that any changes to the graphics state will not be visible outside the group. Sets the source pattern within self to an opaque color. This opaque color will then be used for any subsequent drawing operation until a new source pattern is set. The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. The default source pattern is opaque black, (that is, it is equivalent to Context::set_source_rgb(0.0, 0.0, 0.0)). Sets the source pattern within self to a translucent color. This color will then be used for any subsequent drawing operation until a new source pattern is set. The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. The default source pattern is opaque black, (that is, it is equivalent to Context::set_source_rgba(0.0, 0.0, 0.0, 1.0)). Sets the source pattern within self to source. This pattern will then be used for any subsequent drawing operation until a new source pattern is set. Note: The pattern's transformation matrix will be locked to the user space in effect at the time of Context::set_source(). This means that further modifications of the current transformation matrix will not affect the source pattern. See Pattern::set_matrix(). The default source pattern is a solid pattern that is opaque black, (that is, it is equivalent to Context::set_source_rgb(0.0, 0.0, 0.0)). Gets the current source pattern for self. Set the antialiasing mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value. At the current time, no backend supports CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes. Note that this option does not affect text rendering, instead see FontOptions::set_antialias(). Gets the current shape antialiasing mode, as set by Context::set_antialias(). Sets the dash pattern to be used by cairo_stroke(). A dash pattern is specified by dashes, an array of positive values. Each value provides the length of alternate "on" and "off" portions of the stroke. The offset specifies an offset into the pattern at which the stroke begins. Each "on" segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an "on" length of 0.0 with Line::CapRound or Line::CapSquare in order to distributed dots or squares along a path. Note: The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of Context::set_dash(). If num_dashes is 0 dashing is disabled. If num_dashes is 1 a symmetric pattern is assumed with alternating on and off portions of the size specified by the single value in dashes . If any value in dashes is negative, or if all values are 0, then self will be put into an error state with a status of Status::InvalidDash. This function returns the length of the dash array in self (0 if dashing is not currently in effect). Gets the current dash array. If not NULL, dashes should be big enough to hold at least the number of values returned by Context::get_dash_count(). Set the current fill rule within the cairo context. The fill rule is used to determine which regions are inside or outside a complex (potentially self-intersecting) path. The current fill rule affects both Context::fill() and Context::clip(). See FillRule enum for details on the semantics of each available fill rule. The default fill rule is FillRule::Winding. Gets the current fill rule, as set by Context::set_fill_rule(). Sets the current line cap style within the cairo context. See LineCap enum for details about how the available line cap styles are drawn. As with the other stroke parameters, the current line cap style is examined by Context::stroke(), Context::stroke_extents(), and Context::::stroke_to_path(), but does not have any effect during path construction. The default line cap style is LineCap::Butt. Gets the current line cap style, as set by Context::set_line_cap(). Sets the current line join style within the cairo context. See LineJoin enum for details about how the available line join styles are drawn. As with the other stroke parameters, the current line join style is examined by Context::stroke(), cairo_stroke_extents(), and Context::stroke_to_path(), but does not have any effect during path construction. The default line join style is LineJoin::Miter. Gets the current line join style, as set by Context::set_line_join(). Sets the current line width within the cairo context. The line width value specifies the diameter of a pen that is circular in user space, (though device-space pen may be an ellipse in general due to scaling/shear/rotation of the CTM). Note: When the description above refers to user space and CTM it refers to the user space and CTM in effect at the time of the stroking operation, not the user space and CTM in effect at the time of the call to Context::set_line_width(). The simplest usage makes both of these spaces identical. That is, if there is no change to the CTM between a call to Context::set_line_width() and the stroking operation, then one can just pass user-space values to Context::set_line_width() and ignore this note. As with the other stroke parameters, the current line width is examined by Context::stroke(), Context::stroke_extents(), and Context::stroke_to_path(), but does not have any effect during path construction. The default line width value is 2.0. This function returns the current line width value exactly as set by Context::set_line_width(). Note that the value is unchanged even if the CTM has changed between the calls to Context::set_line_width() and Context::get_line_width(). Sets the current miter limit within the cairo context. If the current line join style is set to LineJoin::Miter (see Context::set_line_join()), the miter limit is used to determine whether the lines should be joined with a bevel instead of a miter. Cairo divides the length of the miter by the line width. If the result is greater than the miter limit, the style is converted to a bevel. As with the other stroke parameters, the current line miter limit is examined by Context::stroke(), Context::stroke_extents(), and Context::stroke_to_path(), but does not have any effect during path construction. The default miter limit value is 10.0, which will convert joins with interior angles less than 11 degrees to bevels instead of miters. For reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 degrees. A miter limit for a desired angle can be computed as: miter limit = 1/sin(angle/2) Gets the current miter limit, as set by Contextset_miter_limit(). Sets the tolerance used when converting paths into trapezoids. Curved segments of the path will be subdivided until the maximum deviation between the original path and the polygonal approximation is less than tolerance . The default value is 0.1. A larger value will give better performance, a smaller value, better appearance. (Reducing the value from the default value of 0.1 is unlikely to improve appearance significantly.) The accuracy of paths within Cairo is limited by the precision of its internal arithmetic, and the prescribed tolerance is restricted to the smallest representable internal value. Gets the current tolerance value, as set by Context::set_tolerance(). Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by Context::fill() and according to the current fill rule (see Context::set_fill_rule()). After Context::clip(), the current path will be cleared from the cairo context. The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region. Calling Context::clip() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling Context::clip() within a Context::save() / Context::restore() pair. The only other means of increasing the size of the clip region is Context::reset_clip(). Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by Context::fill() and according to the current fill rule (see Context::set_fill_rule()). Unlike Context::clip(), Context::clip_preserve() preserves the path within the cairo context. The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region. Calling Context::clip_preserve() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling Context::clip_preserve() within a Context::save()/cairo_restore() pair. The only other means of increasing the size of the clip region is Context::reset_clip(). Computes a bounding box in user coordinates covering the area inside the current clip. Tests whether the given point is inside the area that would be visible through the current clip, i.e. the area that would be filled by a Context::paint() operation. See Context::clip(), and Context::clip_preserve(). Reset the current clip region to its original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface. Note that code meant to be reusable should not call Context::reset_clip() as it will cause results unexpected by higher-level code which calls Context::clip(). Consider using Context::save() and Context::restore() around Context::clip() as a more robust means of temporarily restricting the clip region. Gets the current clip region as a list of rectangles in user coordinates. The status in the list may be Status::ClipNotRepresentable to indicate that the clip region cannot be represented as a list of user-space rectangles. The status may have other values to indicate other errors. A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). After Context::fill(), the current path will be cleared from the cairo context. See Context::set_fill_rule() and Context::fill_preserve(). A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). Unlike Context::fill(), Context::fill_preserve() preserves the path within the cairo context. See Context::set_fill_rule() and Context::fill(). Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a Context::fill() operation given the current path and fill parameters. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account. Contrast with Context::path_extents(), which is similar, but returns non-zero extents for some paths with no inked area, (such as a simple line segment). Note that Context::fill_extents() must necessarily do more work to compute the precise inked areas in light of the fill rule, so Context::path_extents() may be more desirable for sake of performance if the non-inked path extents are desired. See Context::fill(), Context::set_fill_rule() and Context::fill_preserve(). Tests whether the given point is inside the area that would be affected by a Context::fill() operation given the current path and filling parameters. Surface dimensions and clipping are not taken into account. See Context::fill(), Context::set_fill_rule() and Context::fill_preserve(). A drawing operator that paints the current source using the alpha channel of pattern as a mask. (Opaque areas of pattern are painted with the source, transparent areas are not painted.) A drawing operator that paints the current source everywhere within the current clip region. A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha . The effect is similar to Context::paint(), but the drawing is faded out using the alpha value. A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After Context::stroke(), the current path will be cleared from the cairo context. See Context::set_line_width(), Context::set_line_join(), Context::set_line_cap(), Context::set_dash(), and Context::stroke_preserve(). Note: Degenerate segments and sub-paths are treated specially and provide a useful result. These can result in two different situations: 1. Zero-length "on" segments set in Context::set_dash(). If the cap style is LineCap::Round or LineCap::Square then these segments will be drawn as circular dots or squares respectively. In the case of LineCap::Square, the orientation of the squares is determined by the direction of the underlying path. 2. A sub-path created by Context::move_to() followed by either a Context::close_path() or one or more calls to Context::line_to() to the same coordinate as the Context::move_to(). If the cap style is LineCap::Round then these sub-paths will be drawn as circular dots. Note that in the case of LineCap::Square a degenerate sub-path will not be drawn at all, (since the correct orientation is indeterminate). In no case will a cap style of LineCap::Butt cause anything to be drawn in the case of either degenerate segments or sub-paths. A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike Context::stroke(), Context::stroke_preserve() preserves the path within the cairo context. See Context::set_line_width(), Context::set_line_join(), Context::set_line_cap(), Context::set_dash(), and Context::stroke_preserve(). Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a Context::stroke() operation given the current path and stroke parameters. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account. Note that if the line width is set to exactly zero, then Context::stroke_extents() will return an empty rectangle. Contrast with cairo_path_extents() which can be used to compute the non-empty bounds as the line width approaches zero. Note that cairo_stroke_extents() must necessarily do more work to compute the precise inked areas in light of the stroke parameters, so cairo_path_extents() may be more desirable for sake of performance if non-inked path extents are desired. See Context::stroke(), Context::set_line_width(), Context::set_line_join(), Context::set_line_cap(), Context::set_dash(), and Context::stroke_preserve(). Tests whether the given point is inside the area that would be affected by a Context::stroke() operation given the current path and stroking parameters. Surface dimensions and clipping are not taken into account. See Context::stroke(), Context::set_line_width(), Context::set_line_join(), Context::set_line_cap(), Context::set_dash(), and Context::stroke_preserve(). Emits the current page for backends that support multiple pages, but doesn't clear it, so, the contents of the current page will be retained for the next page too. Use Context::show_page() if you want to get an empty page after the emission. This is a convenience function that simply calls Surface::copy_page() on self's target. Emits and clears the current page for backends that support multiple pages. Use Context::copy_page() if you don't want to clear the page. This is a convenience function that simply calls Surface::show_page() on self's target. Returns the current reference count of self. Modifies the current transformation matrix (CTM) by translating the user-space origin by (tx , ty ). This offset is interpreted as a user-space coordinate according to the CTM in place before the new call to cairo_translate(). In other words, the translation of the user-space origin takes place after any existing transformation. Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by sx and sy respectively. The scaling of the axes takes place after any existing transformation of user space. Modifies the current transformation matrix (CTM) by rotating the user-space axes by angle radians. The rotation of the axes takes places after any existing transformation of user space. The rotation direction for positive angles is from the positive X axis toward the positive Y axis. Resets the current transformation matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit. Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM). Transform a distance vector from user space to device space. This function is similar to Context::user_to_device() except that the translation components of the CTM will be ignored when transforming (dx ,dy ). Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM). Transform a distance vector from device space to user space. This function is similar to Context::device_to_user() except that the translation components of the inverse CTM will be ignored when transforming (dx ,dy ). Note: The Context::select_font_face() function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. Selects a family and style of font from a simplified description as a family name, slant and weight. Cairo provides no operation to list available family names on the system (this is a "toy", remember), but the standard CSS2 generic family names, ("serif", "sans-serif", "cursive", "fantasy", "monospace"), are likely to work as expected. If family starts with the string "cairo :", or if no native font backends are compiled in, cairo will use an internal font family. The internal font family recognizes many modifiers in the family string, most notably, it recognizes the string "monospace". That is, the family name "cairo :monospace" will use the monospace version of the internal font family. For "real" font selection, see the font-backend-specific font_face_create functions for the font backend you are using. (For example, if you are using the freetype-based cairo-ft font backend, see Font::create_for_ft_face() or Font::create_for_pattern().) The resulting font face could then be used with Context::scaled_font_create() and Context::set_scaled_font(). Similarly, when using the "real" font support, you can call directly into the underlying font system, (such as fontconfig or freetype), for operations such as listing available fonts, etc. It is expected that most applications will need to use a more comprehensive font handling and text layout library, (for example, pango), in conjunction with cairo. If text is drawn without a call to Context::select_font_face(), (nor Context::set_font_face() nor Context::set_scaled_font()), the default family is platform-specific, but is essentially "sans-serif". Default slant is FontSlant::Normal, and default weight is FontWeight::Normal. This function is equivalent to a call to cairo_toy_font_face_create() followed by Context::set_font_face(). Sets the current font matrix to a scale by a factor of size , replacing any font matrix previously set with Context::set_font_size() or Context::set_font_matrix(). This results in a font size of size user space units. (More precisely, this matrix will result in the font's em-square being a size by size square in user space.) If text is drawn without a call to Context::set_font_size(), (nor Context::set_font_matrix() nor Context::set_scaled_font()), the default font size is 10.0. Stores the current font matrix into matrix . See Context::set_font_matrix(). Sets a set of custom font rendering options for the Context. Rendering options are derived by merging these options with the options derived from underlying surface; if the value in options has a default value (like Antialias::Default), then the value from the surface is used. Retrieves font rendering options set via Context::set_font_options. Note that the returned options do not include any options derived from the underlying surface; they are literally the options passed to Context::set_font_options(). Replaces the current FontFace object in the Context with font_face. The replaced font face in the cairo_t will be destroyed if there are no other references to it. Gets the current font face for a Context object. Replaces the current font face, font matrix, and font options in the Context with those of the ScaledFont object. Except for some translation, the current CTM of the Context should be the same as that of the ScaledFont object, which can be accessed using Context::scaled_font_get_ctm(). Gets the current scaled font for a Context. A drawing operator that generates the shape from a string of UTF-8 characters, rendered according to the current FontFace, FontSize (FontMatrix), and font_options. This function first computes a set of glyphs for the string of text. The first glyph is placed so that its origin is at the current point. The origin of each subsequent glyph is offset from that of the previous glyph by the advance values of the previous glyph. After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for easy display of a single logical string with multiple calls to Context::show_text(). Note: The Context::show_text() function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See Context::show_glyphs() for the "real" text display API in cairo. A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options. Gets the font extents for the currently selected font. Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text, (as it would be drawn by Context::show_text()). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Context::show_text(). Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width and extents.height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values. Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, (as they would be drawn by Context::show_glyphs()). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Context::show_glyphs(). Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height). Creates a copy of the current path and returns it to the user as a Path. See PathData for hints on how to iterate over the returned data structure. This function will always return a valid pointer, but the result will have no data (data==NULL and num_data==0), if either of the following conditions hold: 1. If there is insufficient memory to copy the path. In this case path.status will be set to Status::NoMemory. 2. If self is already in an error state. In this case path.status will contain the same status that would be returned by cairo_status(). Gets a flattened copy of the current path and returns it to the user as a Path. See PathData for hints on how to iterate over the returned data structure. This function is like cairo_copy_path() except that any curves in the path will be approximated with piecewise-linear approximations, (accurate to within the current tolerance value). That is, the result is guaranteed to not have any elements of type Path::CurveTo which will instead be replaced by a series of Path::Line elements. This function will always return a valid pointer, but the result will have no data (data==NULL and num_data==0), if either of the following conditions hold: 1. If there is insufficient memory to copy the path. In this case path->status will be set to Status::NoMemory. 2. If self is already in an error state. In this case path->status will contain the same status that would be returned by Context::status(). Append the path onto the current path. The path may be either the return value from one of Context::copy_path() or Context::copy_path_flat() or it may be constructed manually. See Path for details on how the path data structure should be initialized, and note that path.status must be initialized to Status::Success. Returns whether a current point is defined on the current path. See Context::get_current_point() for details on the current point. Gets the current point of the current path, which is conceptually the final point reached by the path so far. The current point is returned in the user-space coordinate system. If there is no defined current point or if cr is in an error status, x and y will both be set to 0.0. It is possible to check this in advance with cairo_has_current_point(). Most path construction functions alter the current point. See the following for details on how they affect the current point: Context::new_path(), Context::new_sub_path(), Context::append_path(), Context::close_path(), Context::move_to(), Context::line_to(), Context::curve_to(), cairo_rel_move_to(), Context::rel_line_to(), Context::rel_curve_to(), Context::arc(), Context::arc_negative(), Context::rectangle(), Context::text_path(), Context::glyph_path(), Context::stroke_to_path(). Some functions use and alter the current point but do not otherwise change current path: Context::show_text(). Some functions unset the current path and as a result, current point: Context::fill(), Context::stroke(). Clears the current path. After this call there will be no path and no current point. Begin a new sub-path. Note that the existing path is not affected. After this call there will be no current point. In many cases, this call is not needed since new sub-paths are frequently started with Context::move_to(). A call to Context::new_sub_path() is particularly useful when beginning a new sub-path with one of the Context::arc() calls. This makes things easier as it is no longer necessary to manually compute the arc's initial coordinates for a call to Context::move_to(). Adds a line segment to the path from the current point to the beginning of the current sub-path, (the most recent point passed to cairo_move_to()), and closes this sub-path. After this call the current point will be at the joined endpoint of the sub-path. The behavior of Context::close_path() is distinct from simply calling Context::line_to() with the equivalent coordinate in the case of stroking. When a closed sub-path is stroked, there are no caps on the ends of the sub-path. Instead, there is a line join connecting the final and initial segments of the sub-path. If there is no current point before the call to Context::close_path(), this function will have no effect. Note: As of cairo version 1.2.4 any call to Context::close_path() will place an explicit MOVE_TO element into the path immediately after the CLOSE_PATH element, (which can be seen in Context::copy_path() for example). This can simplify path processing in some cases as it may not be necessary to save the "last move_to point" during processing as the MOVE_TO immediately after the CLOSE_PATH will provide that point. Adds a circular arc of the given radius to the current path. The arc is centered at (xc , yc ), begins at angle1 and proceeds in the direction of increasing angles to end at angle2 . If angle2 is less than angle1 it will be progressively increased by 2*M_PI until it is greater than angle1 . If there is a current point, an initial line segment will be added to the path to connect the current point to the beginning of the arc. If this initial line is undesired, it can be avoided by calling Context::new_sub_path() before calling Context::arc(). Angles are measured in radians. An angle of 0.0 is in the direction of the positive X axis (in user space). An angle of M_PI/2.0 radians (90 degrees) is in the direction of the positive Y axis (in user space). Angles increase in the direction from the positive X axis toward the positive Y axis. So with the default transformation matrix, angles increase in a clockwise direction. (To convert from degrees to radians, use degrees * (M_PI / 180.).) This function gives the arc in the direction of increasing angles; see Context::arc_negative() to get the arc in the direction of decreasing angles. The arc is circular in user space. To achieve an elliptical arc, you can scale the current transformation matrix by different amounts in the X and Y directions. For example, to draw an ellipse in the box given by x , y , width , height : ```ignore cr.save(); cr.translate(x + width / 2., y + height / 2.); cr.scale(width / 2., height / 2.); cr.arc(0., 0., 1., 0., 2 * M_PI); cr.restore(); ``` Adds a circular arc of the given radius to the current path. The arc is centered at (xc , yc ), begins at angle1 and proceeds in the direction of decreasing angles to end at angle2 . If angle2 is greater than angle1 it will be progressively decreased by 2*M_PI until it is less than angle1. See Context::arc() for more details. This function differs only in the direction of the arc between the two angles. Adds a cubic Bézier spline to the path from the current point to position (x3 , y3 ) in user-space coordinates, using (x1 , y1 ) and (x2 , y2 ) as the control points. After this call the current point will be (x3 , y3 ). If there is no current point before the call to Context::curve_to() this function will behave as if preceded by a call to Context::move_to(cr , x1 , y1 ). Adds a line to the path from the current point to position (x , y ) in user-space coordinates. After this call the current point will be (x , y ). If there is no current point before the call to cairo_line_to() this function will behave as cairo_move_to(cr , x , y ). Begin a new sub-path. After this call the current point will be (x , y ). Adds a closed sub-path rectangle of the given size to the current path at position (x , y ) in user-space coordinates. This function is logically equivalent to: ```ignore cr.move_to(, x, y); cr.rel_line_to(width, 0); cr.rel_line_to(0, height); cr.rel_line_to(-width, 0); cr.close_path(); ``` Adds closed paths for the glyphs to the current path. The generated path if filled, achieves an effect similar to that of Context::show_glyphs(). Relative-coordinate version of Context::curve_to(). All offsets are relative to the current point. Adds a cubic Bézier spline to the path from the current point to a point offset from the current point by (dx3 , dy3 ), using points offset by (dx1 , dy1 ) and (dx2 , dy2 ) as the control points. After this call the current point will be offset by (dx3 , dy3 ). Given a current point of (x, y), Context::rel_curve_to(dx1 , dy1 , dx2 , dy2 , dx3 , dy3 ) is logically equivalent to Context::curve_to(x+dx1 , y+dy1 , x+dx2 , y+dy2 , x+dx3 , y+dy3 ). It is an error to call this function with no current point. Doing so will cause self to shutdown with a status of Status::NoCurrentPoint. Relative-coordinate version of Context::line_to(). Adds a line to the path from the current point to a point that is offset from the current point by (dx , dy ) in user space. After this call the current point will be offset by (dx , dy ). Given a current point of (x, y), Context::rel_line_to(dx , dy ) is logically equivalent to Context::line_to( x + dx , y + dy ). It is an error to call this function with no current point. Doing so will cause self to shutdown with a status of Status::NoCurrentPoint. Begin a new sub-path. After this call the current point will offset by (x , y ). Given a current point of (x, y), Context::rel_move_to(dx , dy ) is logically equivalent to Context::move_to(x + dx , y + dy ). It is an error to call this function with no current point. Doing so will cause self to shutdown with a status of Status::NoCurrenPoint. FontOptions: How a font should be rendered. FontFace: Base class for font faces. ScaledFont: Font face at particular size and options. The font options specify how fonts should be rendered. Most of the time the font options implied by a surface are just right and do not need any changes, but for pixel-based targets tweaking font options may result in superior output on a particular display. Allocates a new font options object with all options initialized to default values. Checks whether an error has previously occurred for this font options object. Merges non-default options from other into self, replacing existing values. This operation can be thought of as somewhat similar to compositing other onto self with the operation of Operator::Over. Compute a hash for the font options object; this value will be useful when storing an object containing a FontOptions in a hash table. Sets the antialiasing mode for the font options object. This specifies the type of antialiasing to do when rendering text. Gets the antialiasing mode for the font options object. Sets the subpixel order for the font options object. The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of Antialias::Subpixel. See the documentation for SubpixelOrder for full details. Gets the subpixel order for the font options object. See the documentation for SubpixelOrder for full details. Sets the hint style for font outlines for the font options object. This controls whether to fit font outlines to the pixel grid, and if so, whether to optimize for fidelity or contrast. See the documentation for HintStyle for full details. Gets the hint style for font outlines for the font options object. See the documentation for HintStyle for full details. Sets the metrics hinting mode for the font options object. This controls whether metrics are quantized to integer values in device units. See the documentation for HintMetrics for full details. Gets the metrics hinting mode for the font options object. See the documentation for HintMetrics for full details. Compares two font options objects for equality. FontFace represents a particular font at a particular weight, slant, and other characteristic but no size, transformation, or size. Font faces are created using font-backend-specific constructors, typically of the form Context::backend_font_face_create(), or implicitly using the toy text API by way of Context::select_font_face(). The resulting face can be accessed using Context::get_font_face(). Creates a font face from a triplet of family, slant, and weight. These font faces are used in implementation of the the cairo "toy" font API. If family is the zero-length string "", the platform-specific default family is assumed. The default family then can be queried using FontFace::toy_get_family(). The Context::select_font_face() function uses this to create font faces. See that function for limitations and other details of toy font faces. Gets the familly name of a toy font. Gets the slant a toy font. Gets the weight a toy font. Checks whether an error has previously occurred for this font face. This function returns the type of the backend used to create a font face. See FontType for available types. Returns the current reference count of self. Increases the reference count on self by one. This prevents self from being destroyed until a matching call to FontFace drop trait is made. The number of references to a FontFace can be get using FontFace::get_reference_count(). ScaledFont represents a realization of a font face at a particular size and transformation and a certain set of font options. Creates a ScaledFont object from a font face and matrices that describe the size of the font and the environment in which it will be used. Checks whether an error has previously occurred for this ScaledFont. This function returns the type of the backend used to create a scaled font. See FontType for available types. However, this function never returns FontType::Toy. Returns the current reference count of self. Increases the reference count on self by one. This prevents self from being destroyed until a matching call to ScaledFont drop trait is made. The number of references to a cairo_scaled_font_t can be get using ScaledFont::get_reference_count(). Generic matrix operations Creates a new Matrix filled with zeroes Creates a new matrix and fills it with given values Multiplies the affine transformations in a and b together and stores the result in the returned Matrix. The effect of the resulting transformation is to first apply the transformation in left to the coordinates and then apply the transformation in right to the coordinates. It is allowable for the returned Matrix to be identical to either a or . Returns a new matrix after modifying it to be an identity transformation. Sets self to be the affine transformation given by xx , yx , xy , yy , x0 , y0. The transformation is given by: ```ignore x_new = xx * x + xy * y + x0; y_new = yx * x + yy * y + y0; ``` Applies a translation by tx, ty to the transformation in self. The effect of the new transformation is to first translate the coordinates by tx and ty, then apply the original transformation to the coordinates. Applies scaling by sx, sy to the transformation in self. The effect of the new transformation is to first scale the coordinates by sx and sy, then apply the original transformation to the coordinates. Applies rotation by radians to the transformation in self. The effect of the new transformation is to first rotate the coordinates by radians , then apply the original transformation to the coordinates. Inverts a matrix in-place. # Panics Panics if the matrix is not invertible: if the matrix collapses points together (it is degenerate), then it has no inverse and this function will panic. Normally a non-invertible matrix indicates a bug; all matrices that originate from your code should always be valid, invertible matrices. If you construct a matrix from untrusted data and need to validate it, you can use [`try_invert()`]. [`try_invert()`]: #tymethod.try_invert # Example ```ignore use cairo::{Matrix, MatrixTrait}; let mut matrix = Matrix::identity(); matrix.invert(); assert!(matrix == Matrix::identity()); ``` Tries to invert a matrix, and returns the inverted result or an error if the matrix is not invertible. A matrix is not invertible if it collapses points together (it is degenerate). Normally, matrices that originate from your code should always be valid, invertible matrices. You should use this function only to validate matrices that come from untrusted data. # Errors Non-invertible matrices yield an `Err(Status::InvalidMatrix)` error. # Example ```ignore use cairo::{Matrix, MatrixTrait}; let matrix = Matrix::identity(); assert!(matrix.try_invert().unwrap() == Matrix::identity()); let all_zeros_matrix = Matrix::null(); assert!(all_zeros_matrix.try_invert().is_err()); ``` Transforms the distance vector (dx, dy) by self. This is similar to Matrix::transform_point() except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows: ```ignore dx2 = dx1 * a + dy1 * c; dy2 = dx1 * b + dy1 * d; ``` Affine transformations are position invariant, so the same vector always transforms to the same vector. If (x1 ,y1 ) transforms to (x2 ,y2 ) then (x1 +dx1 ,y1 +dy1 ) will transform to (x1 + dx2, y1 + dy2) for all values of x1 and x2 . Transforms the point (x , y) by self. Creating paths and manipulating path data Paths are the most basic drawing tools and are primarily used to implicitly generate simple masks. Sources for drawing Checks whether an error has previously occurred for this pattern. Returns the current reference count of self. Sets the mode to be used for drawing outside the area of a pattern. See cairo_extend_t for details on the semantics of each extend strategy. The default extend mode is Extend::None for surface patterns and Extend::Pad for gradient patterns. Gets the current extend mode for a pattern. See Extend enum for details on the semantics of each extend strategy. Sets the filter to be used for resizing when using this pattern. See Filter enum for details on each filter. Note that you might want to control filtering even when you do not have an explicit Pattern object, (for example when using cairo_set_source_surface()). In these cases, it is convenient to use cairo_get_source() to get access to the pattern that cairo creates implicitly. For example: ```ignore Context::set_source_surface(image, x, y); p.set_filter(Filter::nearest); ``` Gets the current filter for a pattern. See Filter enum for details on each filter. Sets the pattern's transformation matrix, which is a transformation from user space to pattern space. When a pattern is first created it always has the identity matrix for its transformation matrix, which means that pattern space is initially identical to user space. Note that the direction of this transformation matrix is from user space to pattern space. This means that if you imagine the flow from a pattern to user space (and on to device space), then coordinates inthat flow will be transformed by the inverse of the pattern matrix. For example, if you want to make a pattern appear twice as large as it does by default, you should use this code: ```ignore use cairo::{Matrix, MatrixTrait}; let matrix = Matrix::identity().scale (0.5, 0.5); my_pattern.set_matrix (matrix); ``` Gets the current transformation matrix for a pattern. See the documentation for [`set_matrix()`] for the details on this matrix. [`set_matrix()`]: #tymethod.set_matrix Creates a new SolidPattern corresponding to an opaque color. The color components are floating point numbers in the range 0 to 1. Note : If the values passed in are outside that range, they will be clamped. Creates a new SolidPattern corresponding to a translucent color. The color components are floating point numbers in the range 0 to Note : If the values passed in are outside that range, they will be clamped. Gets the solid color for a solid color pattern. Adds an opaque color stop to a gradient pattern. The offset specifies the location along the gradient's control vector. For example, a linear gradient's control vector is from (x0,y0) to (x1,y1) while a radial gradient's control vector is from any point on the start circle to the corresponding point on the end circle. The color is specified in the same way as in Context::set_source_rgba(). If two (or more) stops are specified with identical offset values, they will be sorted according to the order in which the stops are added, (stops added earlier will compare less than stops added later). This can be useful for reliably making sharp color transitions instead of the typical blend. Note: If the pattern is not a gradient pattern, (eg. a linear or radial pattern), then the pattern will be put into an error status with a status of StatusPattern::TypeMismatch. Adds a translucent color stop to a gradient pattern. The offset specifies the location along the gradient's control vector. For example, a linear gradient's control vector is from (x0,y0) to (x1,y1) while a radial gradient's control vector is from any point on the start circle to the corresponding point on the end circle. The color is specified in the same way as in Context::set_source_rgba(). If two (or more) stops are specified with identical offset values, they will be sorted according to the order in which the stops are added, (stops added earlier will compare less than stops added later). This can be useful for reliably making sharp color transitions instead of the typical blend. Note: If the pattern is not a gradient pattern, (eg. a linear or radial pattern), then the pattern will be put into an error status with a status of StatusPattern::TypeMismatch. Gets the number of color stops specified in the given gradient pattern. Gets the color and offset information at the given index for a gradient pattern. Values of index range from 0 to n-1 where n is the number returned by Pattern::get_color_stop_count(). Create a new linear gradient Pattern object along the line defined by (x0, y0) and (x1, y1). Before using the gradient pattern, a number of color stops should be defined using Pattern::add_color_stop_rgb() or Pattern::add_color_stop_rgba(). Note: The coordinates here are in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with Pattern::set_matrix(). Gets the gradient endpoints for a linear gradient. Creates a new radial gradient Pattern between the two circles defined by (cx0, cy0, radius0) and (cx1, cy1, radius1). Before using the gradient pattern, a number of color stops should be defined using Pattern::add_color_stop_rgb() or Pattern::add_color_stop_rgba(). Note: The coordinates here are in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with Pattern::set_matrix(). Gets the gradient endpoint circles for a radial gradient, each specified as a center coordinate and a radius. Create a new mesh pattern. Mesh patterns are tensor-product patch meshes (type 7 shadings in PDF). Mesh patterns may also be used to create other types of shadings that are special cases of tensor-product patch meshes such as Coons patch meshes (type 6 shading in PDF) and Gouraud-shaded triangle meshes (type 4 and 5 shadings in PDF). Mesh patterns consist of one or more tensor-product patches, which should be defined before using the mesh pattern. Using a mesh pattern with a partially defined patch as source or mask will put the context in an error status with a status of Status::InvalidMeshConstruction. A tensor-product patch is defined by 4 Bézier curves (side 0, 1, 2, 3) and by 4 additional control points (P0, P1, P2, P3) that provide further control over the patch and complete the definition of the tensor-product patch. The corner C0 is the first point of the patch. Degenerate sides are permitted so straight lines may be used. A zero length line on one side may be used to create 3 sided patches. ```text C1 Side 1 C2 +---------------+ | | | P1 P2 | | | Side 0 | | Side 2 | | | | | P0 P3 | | | +---------------+ C0 Side 3 C3 ``` Each patch is constructed by first calling Mesh::begin_patch(), then Mesh::move_to() to specify the first point in the patch (C0). Then the sides are specified with calls to Mesh::curve_to() and cairo_mesh_pattern_line_to(). The four additional control points (P0, P1, P2, P3) in a patch can be specified with Mesh::set_control_point(). At each corner of the patch (C0, C1, C2, C3) a color may be specified with Mesh::set_corner_color_rgb() or Mesh::set_corner_color_rgba(). Any corner whose color is not explicitly specified defaults to transparent black. A Coons patch is a special case of the tensor-product patch where the control points are implicitly defined by the sides of the patch. The default value for any control point not specified is the implicit value for a Coons patch, i.e. if no control points are specified the patch is a Coons patch. A triangle is a special case of the tensor-product patch where the control points are implicitly defined by the sides of the patch, all the sides are lines and one of them has length 0, i.e. if the patch is specified using just 3 lines, it is a triangle. If the corners connected by the 0-length side have the same color, the patch is a Gouraud-shaded triangle. Patches may be oriented differently to the above diagram. For example the first point could be at the top left. The diagram only shows the relationship between the sides, corners and control points. Regardless of where the first point is located, when specifying colors, corner 0 will always be the first point, corner 1 the point between side 0 and side 1 etc. Calling Mesh::end_patch() completes the current patch. If less than 4 sides have been defined, the first missing side is defined as a line from the current point to the first point of the patch (C0) and the other sides are degenerate lines from C0 to C0. The corners between the added sides will all be coincident with C0 of the patch and their color will be set to be the same as the color of C0. Additional patches may be added with additional calls to Mesh::begin_patch()/Mesh::end_patch(). ```ignore let mut pattern = Mesh::new(); Add a Coons patch pattern.begin_patch(); pattern.move_to(0, 0); pattern.curve_to(30, -30, 60, 30, 100, 0); pattern.curve_to(60, 30, 130, 60, 100, 100); pattern.curve_to(60, 70, 30, 130, 0, 100); pattern.curve_to(30, 70, -30, 30, 0, 0); pattern.set_corner_color_rgb(0, 1, 0, 0); pattern.set_corner_color_rgb(1, 0, 1, 0); pattern.set_corner_color_rgb(2, 0, 0, 1); pattern.set_corner_color_rgb(3, 1, 1, 0); pattern.end_patch(); Add a Gouraud-shaded triangle pattern.begin_patch() pattern.move_to(100, 100); pattern.line_to(130, 130); pattern.line_to(130, 70); pattern.set_corner_color_rgb(0, 1, 0, 0); pattern.set_corner_color_rgb(1, 0, 1, 0); pattern.set_corner_color_rgb(2, 0, 0, 1); pattern.end_patch(); ``` When two patches overlap, the last one that has been added is drawn over the first one. When a patch folds over itself, points are sorted depending on their parameter coordinates inside the patch. The v coordinate ranges from 0 to 1 when moving from side 3 to side 1; the u coordinate ranges from 0 to 1 when going from side 0 to side Points with higher v coordinate hide points with lower v coordinate. When two points have the same v coordinate, the one with higher u coordinate is above. This means that points nearer to side 1 are above points nearer to side 3; when this is not sufficient to decide which point is above (for example when both points belong to side 1 or side 3) points nearer to side 2 are above points nearer to side 0. For a complete definition of tensor-product patches, see the PDF specification (ISO32000), which describes the parametrization in detail. Note: The coordinates are always in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with Pattern::set_matrix(). Begin a patch in a mesh pattern. After calling this function, the patch shape should be defined with Mesh::move_to(), Mesh::line_to() and Mesh::curve_to(). After defining the patch, Mesh::end_patch() must be called before using pattern as a source or mask. Note: If pattern is not a mesh pattern then pattern will be put into an error status with a status of Status::PatternTypeMismatch. If pattern already has a current patch, it will be put into an error status with a status of Status::InvalidMeshConstruction. Indicates the end of the current patch in a mesh pattern. If the current patch has less than 4 sides, it is closed with a straight line from the current point to the first point of the patch as if Mesh::line_to() was used. Note: If pattern is not a mesh pattern then pattern will be put into an error status with a status of Status::PatternTypeMismatch. If pattern has no current patch or the current patch has no current point, pattern will be put into an error status with a status of Status::InvalidMeshConstruction. Define the first point of the current patch in a mesh pattern. After this call the current point will be (x , y ). Note: If pattern is not a mesh pattern then pattern will be put into an error status with a status of Status::PatternTypeMismatch. If pattern has no current patch or the current patch already has at least one side, pattern will be put into an error status with a status of Status::InvalidMeshConstruction. Adds a line to the current patch from the current point to position (x , y ) in pattern-space coordinates. If there is no current point before the call to cairo_mesh_pattern_line_to() this function will behave as Mesh::move_to(pattern , x , y ). After this call the current point will be (x , y ). Note: If pattern is not a mesh pattern then pattern will be put into an error status with a status of Status::PatternTypeMismatch. If pattern has no current patch or the current patch already has 4 sides, pattern will be put into an error status with a status of Status::InvalidMeshConstruction. Adds a cubic Bézier spline to the current patch from the current point to position (x3 , y3 ) in pattern-space coordinates, using (x1 , y1 ) and (x2 , y2 ) as the control points. If the current patch has no current point before the call to Mesh::curve_to(), this function will behave as if preceded by a call to Mesh::move_to(pattern , x1 , y1 ). After this call the current point will be (x3 , y3 ). Note: If pattern is not a mesh pattern then pattern will be put into an error status with a status of Status::PatternTypeMismatch. If pattern has no current patch or the current patch already has 4 sides, pattern will be put into an error status with a status of Status::InvalidMeshConstruction. Set an internal control point of the current patch. Valid values for point_num are from 0 to 3 and identify the control points as explained in Mesh::new(). Note: If pattern is not a mesh pattern then pattern will be put into an error status with a status of Status::PatternTypeMismatch. If point_num is not valid, pattern will be put into an error status with a status of Status::InvalidIndex. If pattern has no current patch, pattern will be put into an error status with a status of Status::InvalidMeshConstruction. Gets the control point point_num of patch patch_num for a mesh pattern. patch_num can range from 0 to n-1 where n is the number returned by Mesh::get_patch_count(). Valid values for point_num are from 0 to 3 and identify the control points as explained in Mesh::new(). Sets the color of a corner of the current patch in a mesh pattern. The color is specified in the same way as in Context::set_source_rgb(). Valid values for corner_num are from 0 to 3 and identify the corners as explained in Mesh::new(). Note: If pattern is not a mesh pattern then pattern will be put into an error status with a status of Status::PatternTypeMismatch. If corner_num is not valid, pattern will be put into an error status with a status of Status::InvalidIndex. If pattern has no current patch, pattern will be put into an error status with a status of Status::InvalidMeshConstruction. Sets the color of a corner of the current patch in a mesh pattern. The color is specified in the same way as in Context::set_source_rgba(). Valid values for corner_num are from 0 to 3 and identify the corners as explained in Mesh::new(). Note: If pattern is not a mesh pattern then pattern will be put into an error status with a status of Status::PatternTypeMismatch. If corner_num is not valid, pattern will be put into an error status with a status of Status::InvalidIndex. If pattern has no current patch, pattern will be put into an error status with a status of Status::InvalidMeshConstruction. Gets the color information in corner corner_num of patch patch_num for a mesh pattern. patch_num can range from 0 to n-1 where n is the number returned by Mesh::get_patch_count(). Valid values for corner_num are from 0 to 3 and identify the corners as explained in Mesh::new(). Gets the number of patches specified in the given mesh pattern. The number only includes patches which have been finished by calling Mesh::end_patch(). For example it will be 0 during the definition of the first patch. Gets path defining the patch patch_num for a mesh pattern. patch_num can range from 0 to n-1 where n is the number returned by Mesh::get_patch_count(). A PDF surface that writes to a file Create a new PDF file surface. ``` use cairo::Context; use cairo::pdf; use cairo::prelude::*; let surface = pdf::File::new(100.0, 100.0, "test.pdf"); let context = Context::new(&surface); // Draw things on the context. surface.finish(); ``` Specify what PDF version to generate. A PDF surface that writes to a generic `io::Write` type (owning variant) The `Writer` takes ownership of the write object. Once you're done using the surface, you can obtain the write object back using the `finish()` method. If you would like the surface to reference the write object instead, use `RefWriter`. Create a new writer surface. ``` use std::fs::File; use cairo::Context; use cairo::pdf; use cairo::prelude::*; let surface = pdf::Writer::new(100.0, 100.0, File::create("test.pdf").unwrap()); let context = Context::new(&surface); // Draw things on the context. surface.finish(); ``` Specify what PDF version to generate. Streaming PDF surface. Create a new streaming surface. ``` use std::fs::File; use std::io::Write; use cairo::Context; use cairo::pdf; use cairo::prelude::*; let mut file = File::create("test.pdf").unwrap(); let surface = pdf::Writer::new(100.0, 100.0, file); let context = Context::new(&surface); // Draw things on the context. surface.finish(); ``` Specify what PDF version to generate. A PDF surface that writes to a generic `io::Write` type (owning variant) The `Writer` takes ownership of the write object. Once you're done using the surface, you can obtain the write object back using the `finish()` method. If you would like the surface to reference the write object instead, use `RefWriter`. A PDF surface that writes to a generic `io::Write` type (referencing variant) The `RefWriter` references the write object, which is why a lifetime parameter is required. If you would like the surface to own the write object instead, use `Writer`. A PostScript surface that writes to a file Create a new PostScript file surface. ``` use cairo::Context; use cairo::ps; use cairo::prelude::*; let surface = ps::File::new(100.0, 100.0, "test.ps"); let context = Context::new(&surface); // Draw things on the context. surface.finish(); ``` Specify what PostScript level to generate. A PostScript surface that writes to a generic `io::Write` type (owning variant) The `Writer` takes ownership of the write object. Once you're done using the surface, you can obtain the write object back using the `finish()` method. If you would like the surface to reference the write object instead, use `RefWriter`. Create a new writer surface. ``` use std::fs::File; use cairo::Context; use cairo::ps; use cairo::prelude::*; let surface = ps::Writer::new(100.0, 100.0, File::create("test.ps").unwrap()); let context = Context::new(&surface); // Draw things on the context. surface.finish(); ``` Specify what PostScript level to generate. Streaming PDF surface. Create a new streaming surface. ``` use std::fs::File; use std::io::Write; use cairo::Context; use cairo::ps; use cairo::prelude::*; let mut file = File::create("test.ps").unwrap(); let surface = ps::Writer::new(100.0, 100.0, file); let context = Context::new(&surface); // Draw things on the context. surface.finish(); ``` Specify what PostScript level to generate. A PostScript surface that writes to a generic `io::Write` type (referencing variant) The `RefWriter` references the write object, which is why a lifetime parameter is required. If you would like the surface to own the write object instead, use `Writer`. Handles dark magic to maintain a stream closure based surface. The closure is boxed twice so it can be passed around as a `*mut c_void`, and it's then converted back into an usable trait object by removing the lifetime. This seems to be okay because the closure is alive as long as the surface is. Uses the `Stream` abstraction to implement streaming on a `T: io::Write`, nothing fancy going on here. Uses the `Stream` abstraction to implement streaming to a buffer bound to the surface. The `Vec` is actually kept around as a `*mut Vec` since the closure will be alive as long as the vector. An SVG surface that writes to a file Create a new SVG file surface. ``` use cairo::Context; use cairo::svg; use cairo::prelude::*; let surface = svg::File::new(100.0, 100.0, "test.svg"); let context = Context::new(&surface); // Draw things on the context. surface.finish(); ``` Specify what SVG version to generate. An SVG surface that writes to a generic `io::Write` type (owning variant) The `Writer` takes ownership of the write object. Once you're done using the surface, you can obtain the write object back using the `finish()` method. If you would like the surface to reference the write object instead, use `RefWriter`. Create a new writer surface. ``` use std::fs::File; use cairo::Context; use cairo::svg; use cairo::prelude::*; let surface = svg::Writer::new(100.0, 100.0, File::create("test.svg").unwrap()); let context = Context::new(&surface); // Draw things on the context. surface.finish(); ``` Specify what SVG version to generate. An SVG surface that writes to a generic `io::Write` type (referencing variant) The `RefWriter` references the write object, which is why a lifetime parameter is required. If you would like the surface to own the write object instead, use `Writer`. A key for indexing user data in various cairo types. Some types like [`Surface`] have `get_user_data`, `set_user_data`, and `remove_user_data` methods that take `&'static UserDataKey`, where the address of that reference is significant. To reliably have a stable address, the expected usage is to define a `static` item: ``` use cairo::UserDataKey; static FOO: UserDataKey = UserDataKey::new(); # fn foo(surface: &cairo::Surface) { surface.get_user_data(&FOO) # ; } ``` gtk-rs-lgpl-docs-0.1.12/Cargo.toml.orig010064400007650000024000000005471350423670400160040ustar0000000000000000[package] name = "gtk-rs-lgpl-docs" version = "0.1.12" authors = [ "GTK+ Project Developers", "Gtk-rs Project Developers", ] license = "LGPL-2.0" description = "LGPL-licensed docs for Gtk-rs crates" repository = "https://github.com/gtk-rs/lgpl-docs" homepage = "http://gtk-rs.org/" [lib] name = "lgpl_docs" [dependencies] rustdoc-stripper = "0.1.6" gtk-rs-lgpl-docs-0.1.12/Cargo.toml0000644000000015600000000000000122450ustar00# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies # # If you believe there's an error in this file please file an # issue against the rust-lang/cargo repository. If you're # editing this file be aware that the upstream Cargo.toml # will likely look very different (and much more reasonable) [package] name = "gtk-rs-lgpl-docs" version = "0.1.12" authors = ["GTK+ Project Developers", "Gtk-rs Project Developers"] description = "LGPL-licensed docs for Gtk-rs crates" homepage = "http://gtk-rs.org/" license = "LGPL-2.0" repository = "https://github.com/gtk-rs/lgpl-docs" [lib] name = "lgpl_docs" [dependencies.rustdoc-stripper] version = "0.1.6" gtk-rs-lgpl-docs-0.1.12/gdk-pixbuf/docs.md010064400007650000024000000000201344544746500164250ustar0000000000000000 gtk-rs-lgpl-docs-0.1.12/gdk-pixbuf/vendor.md010064400007650000024000002023541350423663000167720ustar0000000000000000 This enumeration defines the color spaces that are supported by the gdk-pixbuf library. Currently only RGB is supported. Indicates a red/green/blue additive color space. This enumeration describes the different interpolation modes that can be used with the scaling functions. `InterpType::Nearest` is the fastest scaling method, but has horrible quality when scaling down. `InterpType::Bilinear` is the best choice if you aren't sure what to choose, it has a good speed/quality balance. **Note**: Cubic filtering is missing from the list; hyperbolic interpolation is just as fast and results in higher quality. Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up. This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction. Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area. This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping). **Deprecated**: this interpolation filter is deprecated, as in reality it has a lower quality than the `InterpType::Bilinear` filter (Since: 2.38) This is the main structure in the gdk-pixbuf library. It is used to represent images. It contains information about the image's pixel data, its color space, bits per sample, width and height, and the rowstride (the number of bytes between the start of one row and the start of the next). # Implements [`gio::IconExt`](../gio/trait.IconExt.html), [`gio::LoadableIconExt`](../gio/trait.LoadableIconExt.html) Creates a new `Pixbuf` structure and allocates a buffer for it. The buffer has an optimal rowstride. Note that the buffer is not cleared; you will have to fill it completely yourself. ## `colorspace` Color space for image ## `has_alpha` Whether the image should have transparency information ## `bits_per_sample` Number of bits per color sample ## `width` Width of image in pixels, must be > 0 ## `height` Height of image in pixels, must be > 0 # Returns A newly-created `Pixbuf` with a reference count of 1, or `None` if not enough memory could be allocated for the image buffer. Creates a new `Pixbuf` out of in-memory readonly image data. Currently only RGB images with 8 bits per sample are supported. This is the `glib::Bytes` variant of `Pixbuf::new_from_data`. Feature: `v2_32` ## `data` Image data in 8-bit/sample packed format inside a `glib::Bytes` ## `colorspace` Colorspace for the image data ## `has_alpha` Whether the data has an opacity channel ## `bits_per_sample` Number of bits per sample ## `width` Width of the image in pixels, must be > 0 ## `height` Height of the image in pixels, must be > 0 ## `rowstride` Distance in bytes between row starts # Returns A newly-created `Pixbuf` structure with a reference count of 1. Creates a new `Pixbuf` out of in-memory image data. Currently only RGB images with 8 bits per sample are supported. Since you are providing a pre-allocated pixel buffer, you must also specify a way to free that data. This is done with a function of type ``GdkPixbufDestroyNotify``. When a pixbuf created with is finalized, your destroy notification function will be called, and it is its responsibility to free the pixel array. See also `Pixbuf::new_from_bytes`. ## `data` Image data in 8-bit/sample packed format ## `colorspace` Colorspace for the image data ## `has_alpha` Whether the data has an opacity channel ## `bits_per_sample` Number of bits per sample ## `width` Width of the image in pixels, must be > 0 ## `height` Height of the image in pixels, must be > 0 ## `rowstride` Distance in bytes between row starts ## `destroy_fn` Function used to free the data when the pixbuf's reference count drops to zero, or `None` if the data should not be freed ## `destroy_fn_data` Closure data to pass to the destroy notification function # Returns A newly-created `Pixbuf` structure with a reference count of 1. Creates a new pixbuf by loading an image from a file. The file format is detected automatically. If `None` is returned, then `error` will be set. Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains. ## `filename` Name of file to load, in the GLib file name encoding # Returns A newly-created pixbuf with a reference count of 1, or `None` if any of several error conditions occurred: the file could not be opened, there was no loader for the file's format, there was not enough memory to allocate the image buffer, or the image file contained invalid data. Creates a new pixbuf by loading an image from a file. The file format is detected automatically. If `None` is returned, then `error` will be set. Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. When preserving the aspect ratio, a `width` of -1 will cause the image to be scaled to the exact given height, and a `height` of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, a `width` or `height` of -1 means to not scale the image at all in that dimension. Negative values for `width` and `height` are allowed since 2.8. ## `filename` Name of file to load, in the GLib file name encoding ## `width` The width the image should have or -1 to not constrain the width ## `height` The height the image should have or -1 to not constrain the height ## `preserve_aspect_ratio` `true` to preserve the image's aspect ratio # Returns A newly-created pixbuf with a reference count of 1, or `None` if any of several error conditions occurred: the file could not be opened, there was no loader for the file's format, there was not enough memory to allocate the image buffer, or the image file contained invalid data. Creates a new pixbuf by loading an image from a file. The file format is detected automatically. If `None` is returned, then `error` will be set. Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains. The image will be scaled to fit in the requested size, preserving the image's aspect ratio. Note that the returned pixbuf may be smaller than `width` x `height`, if the aspect ratio requires it. To load and image at the requested size, regardless of aspect ratio, use `Pixbuf::new_from_file_at_scale`. ## `filename` Name of file to load, in the GLib file name encoding ## `width` The width the image should have or -1 to not constrain the width ## `height` The height the image should have or -1 to not constrain the height # Returns A newly-created pixbuf with a reference count of 1, or `None` if any of several error conditions occurred: the file could not be opened, there was no loader for the file's format, there was not enough memory to allocate the image buffer, or the image file contained invalid data. Create a `Pixbuf` from a flat representation that is suitable for storing as inline data in a program. This is useful if you want to ship a program with images, but don't want to depend on any external files. gdk-pixbuf ships with a program called [gdk-pixbuf-csource][gdk-pixbuf-csource], which allows for conversion of ``GdkPixbufs`` into such a inline representation. In almost all cases, you should pass the `--raw` option to `gdk-pixbuf-csource`. A sample invocation would be: ```text gdk-pixbuf-csource --raw --name=myimage_inline myimage.png ``` For the typical case where the inline pixbuf is read-only static data, you don't need to copy the pixel data unless you intend to write to it, so you can pass `false` for `copy_pixels`. (If you pass `--rle` to `gdk-pixbuf-csource`, a copy will be made even if `copy_pixels` is `false`, so using this option is generally a bad idea.) If you create a pixbuf from const inline data compiled into your program, it's probably safe to ignore errors and disable length checks, since things will always succeed: ```text pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL); ``` For non-const inline data, you could get out of memory. For untrusted inline data located at runtime, you could have corrupt inline data in addition. # Deprecated since 2.32 Use `gio::Resource` instead. ## `data_length` Length in bytes of the `data` argument or -1 to disable length checks ## `data` Byte data containing a serialized ``GdkPixdata`` structure ## `copy_pixels` Whether to copy the pixel data, or use direct pointers `data` for the resulting pixbuf # Returns A newly-created `Pixbuf` structure with a reference, count of 1, or `None` if an error occurred. Creates a new pixbuf by loading an image from an resource. The file format is detected automatically. If `None` is returned, then `error` will be set. ## `resource_path` the path of the resource file # Returns A newly-created pixbuf, or `None` if any of several error conditions occurred: the file could not be opened, the image format is not supported, there was not enough memory to allocate the image buffer, the stream contained invalid data, or the operation was cancelled. Creates a new pixbuf by loading an image from an resource. The file format is detected automatically. If `None` is returned, then `error` will be set. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. When preserving the aspect ratio, a `width` of -1 will cause the image to be scaled to the exact given height, and a `height` of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, a `width` or `height` of -1 means to not scale the image at all in that dimension. The stream is not closed. ## `resource_path` the path of the resource file ## `width` The width the image should have or -1 to not constrain the width ## `height` The height the image should have or -1 to not constrain the height ## `preserve_aspect_ratio` `true` to preserve the image's aspect ratio # Returns A newly-created pixbuf, or `None` if any of several error conditions occurred: the file could not be opened, the image format is not supported, there was not enough memory to allocate the image buffer, the stream contained invalid data, or the operation was cancelled. Creates a new pixbuf by loading an image from an input stream. The file format is detected automatically. If `None` is returned, then `error` will be set. The `cancellable` can be used to abort the operation from another thread. If the operation was cancelled, the error `gio::IOErrorEnum::Cancelled` will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The stream is not closed. ## `stream` a `gio::InputStream` to load the pixbuf from ## `cancellable` optional `gio::Cancellable` object, `None` to ignore # Returns A newly-created pixbuf, or `None` if any of several error conditions occurred: the file could not be opened, the image format is not supported, there was not enough memory to allocate the image buffer, the stream contained invalid data, or the operation was cancelled. Creates a new pixbuf by loading an image from an input stream. The file format is detected automatically. If `None` is returned, then `error` will be set. The `cancellable` can be used to abort the operation from another thread. If the operation was cancelled, the error `gio::IOErrorEnum::Cancelled` will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. When preserving the aspect ratio, a `width` of -1 will cause the image to be scaled to the exact given height, and a `height` of -1 will cause the image to be scaled to the exact given width. If both `width` and `height` are given, this function will behave as if the smaller of the two values is passed as -1. When not preserving aspect ratio, a `width` or `height` of -1 means to not scale the image at all in that dimension. The stream is not closed. ## `stream` a `gio::InputStream` to load the pixbuf from ## `width` The width the image should have or -1 to not constrain the width ## `height` The height the image should have or -1 to not constrain the height ## `preserve_aspect_ratio` `true` to preserve the image's aspect ratio ## `cancellable` optional `gio::Cancellable` object, `None` to ignore # Returns A newly-created pixbuf, or `None` if any of several error conditions occurred: the file could not be opened, the image format is not supported, there was not enough memory to allocate the image buffer, the stream contained invalid data, or the operation was cancelled. Finishes an asynchronous pixbuf creation operation started with `Pixbuf::new_from_stream_async`. ## `async_result` a `gio::AsyncResult` # Returns a `Pixbuf` or `None` on error. Free the returned object with `gobject::Object::unref`. Creates a new pixbuf by parsing XPM data in memory. This data is commonly the result of including an XPM file into a program's C source. ## `data` Pointer to inline XPM data. # Returns A newly-created pixbuf with a reference count of 1. Calculates the rowstride that an image created with those values would have. This is useful for front-ends and backends that want to sanity check image values without needing to create them. Feature: `v2_36_8` ## `colorspace` Color space for image ## `has_alpha` Whether the image should have transparency information ## `bits_per_sample` Number of bits per color sample ## `width` Width of image in pixels, must be > 0 ## `height` Height of image in pixels, must be > 0 # Returns the rowstride for the given values, or -1 in case of error. Parses an image file far enough to determine its format and size. ## `filename` The name of the file to identify. ## `width` Return location for the width of the image, or `None` ## `height` Return location for the height of the image, or `None` # Returns A `PixbufFormat` describing the image format of the file or `None` if the image format wasn't recognized. The return value is owned by `Pixbuf` and should not be freed. Asynchronously parses an image file far enough to determine its format and size. For more details see `Pixbuf::get_file_info`, which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call `Pixbuf::get_file_info_finish` to get the result of the operation. Feature: `v2_32` ## `filename` The name of the file to identify ## `cancellable` optional `gio::Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the file info is available ## `user_data` the data to pass to the callback function Finishes an asynchronous pixbuf parsing operation started with `Pixbuf::get_file_info_async`. Feature: `v2_32` ## `async_result` a `gio::AsyncResult` ## `width` Return location for the width of the image, or `None` ## `height` Return location for the height of the image, or `None` # Returns A `PixbufFormat` describing the image format of the file or `None` if the image format wasn't recognized. The return value is owned by `Pixbuf` and should not be freed. Obtains the available information about the image formats supported by `Pixbuf`. # Returns A list of ``GdkPixbufFormats`` describing the supported image formats. The list should be freed when it is no longer needed, but the structures themselves are owned by `Pixbuf` and should not be freed. Creates a new pixbuf by asynchronously loading an image from an input stream. For more details see `Pixbuf::new_from_stream`, which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call `Pixbuf::new_from_stream_finish` to get the result of the operation. ## `stream` a `gio::InputStream` from which to load the pixbuf ## `cancellable` optional `gio::Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the pixbuf is loaded ## `user_data` the data to pass to the callback function Creates a new pixbuf by asynchronously loading an image from an input stream. For more details see `Pixbuf::new_from_stream_at_scale`, which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call `Pixbuf::new_from_stream_finish` to get the result of the operation. ## `stream` a `gio::InputStream` from which to load the pixbuf ## `width` the width the image should have or -1 to not constrain the width ## `height` the height the image should have or -1 to not constrain the height ## `preserve_aspect_ratio` `true` to preserve the image's aspect ratio ## `cancellable` optional `gio::Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the pixbuf is loaded ## `user_data` the data to pass to the callback function Finishes an asynchronous pixbuf save operation started with `Pixbuf::save_to_stream_async`. ## `async_result` a `gio::AsyncResult` # Returns `true` if the pixbuf was saved successfully, `false` if an error was set. Takes an existing pixbuf and adds an alpha channel to it. If the existing pixbuf already had an alpha channel, the channel values are copied from the original; otherwise, the alpha channel is initialized to 255 (full opacity). If `substitute_color` is `true`, then the color specified by (`r`, `g`, `b`) will be assigned zero opacity. That is, if you pass (255, 255, 255) for the substitute color, all white pixels will become fully transparent. ## `substitute_color` Whether to set a color to zero opacity. If this is `false`, then the (`r`, `g`, `b`) arguments will be ignored. ## `r` Red value to substitute. ## `g` Green value to substitute. ## `b` Blue value to substitute. # Returns A newly-created pixbuf with a reference count of 1. Takes an existing pixbuf and checks for the presence of an associated "orientation" option, which may be provided by the jpeg loader (which reads the exif orientation tag) or the tiff loader (which reads the tiff orientation tag, and compensates it for the partial transforms performed by libtiff). If an orientation option/tag is present, the appropriate transform will be performed so that the pixbuf is oriented correctly. # Returns A newly-created pixbuf, `None` if not enough memory could be allocated for it, or a reference to the input pixbuf (with an increased reference count). Creates a transformation of the source image `self` by scaling by `scale_x` and `scale_y` then translating by `offset_x` and `offset_y`. This gives an image in the coordinates of the destination pixbuf. The rectangle (`dest_x`, `dest_y`, `dest_width`, `dest_height`) is then alpha blended onto the corresponding rectangle of the original destination image. When the destination rectangle contains parts not in the source image, the data at the edges of the source image is replicated to infinity. ![](composite.png) ## `dest` the `Pixbuf` into which to render the results ## `dest_x` the left coordinate for region to render ## `dest_y` the top coordinate for region to render ## `dest_width` the width of the region to render ## `dest_height` the height of the region to render ## `offset_x` the offset in the X direction (currently rounded to an integer) ## `offset_y` the offset in the Y direction (currently rounded to an integer) ## `scale_x` the scale factor in the X direction ## `scale_y` the scale factor in the Y direction ## `interp_type` the interpolation type for the transformation. ## `overall_alpha` overall alpha for source image (0..255) Creates a transformation of the source image `self` by scaling by `scale_x` and `scale_y` then translating by `offset_x` and `offset_y`, then alpha blends the rectangle (`dest_x` ,`dest_y`, `dest_width`, `dest_height`) of the resulting image with a checkboard of the colors `color1` and `color2` and renders it onto the destination image. If the source image has no alpha channel, and `overall_alpha` is 255, a fast path is used which omits the alpha blending and just performs the scaling. See `Pixbuf::composite_color_simple` for a simpler variant of this function suitable for many tasks. ## `dest` the `Pixbuf` into which to render the results ## `dest_x` the left coordinate for region to render ## `dest_y` the top coordinate for region to render ## `dest_width` the width of the region to render ## `dest_height` the height of the region to render ## `offset_x` the offset in the X direction (currently rounded to an integer) ## `offset_y` the offset in the Y direction (currently rounded to an integer) ## `scale_x` the scale factor in the X direction ## `scale_y` the scale factor in the Y direction ## `interp_type` the interpolation type for the transformation. ## `overall_alpha` overall alpha for source image (0..255) ## `check_x` the X offset for the checkboard (origin of checkboard is at -`check_x`, -`check_y`) ## `check_y` the Y offset for the checkboard ## `check_size` the size of checks in the checkboard (must be a power of two) ## `color1` the color of check at upper left ## `color2` the color of the other check Creates a new `Pixbuf` by scaling `self` to `dest_width` x `dest_height` and alpha blending the result with a checkboard of colors `color1` and `color2`. ## `dest_width` the width of destination image ## `dest_height` the height of destination image ## `interp_type` the interpolation type for the transformation. ## `overall_alpha` overall alpha for source image (0..255) ## `check_size` the size of checks in the checkboard (must be a power of two) ## `color1` the color of check at upper left ## `color2` the color of the other check # Returns the new `Pixbuf`, or `None` if not enough memory could be allocated for it. Creates a new `Pixbuf` with a copy of the information in the specified `self`. Note that this does not copy the options set on the original `Pixbuf`, use `Pixbuf::copy_options` for this. # Returns A newly-created pixbuf with a reference count of 1, or `None` if not enough memory could be allocated. Copies a rectangular area from `self` to `dest_pixbuf`. Conversion of pixbuf formats is done automatically. If the source rectangle overlaps the destination rectangle on the same pixbuf, it will be overwritten during the copy operation. Therefore, you can not use this function to scroll a pixbuf. ## `src_x` Source X coordinate within `self`. ## `src_y` Source Y coordinate within `self`. ## `width` Width of the area to copy. ## `height` Height of the area to copy. ## `dest_pixbuf` Destination pixbuf. ## `dest_x` X coordinate within `dest_pixbuf`. ## `dest_y` Y coordinate within `dest_pixbuf`. Copy the key/value pair options attached to a `Pixbuf` to another. This is useful to keep original metadata after having manipulated a file. However be careful to remove metadata which you've already applied, such as the "orientation" option after rotating the image. Feature: `v2_36` ## `dest_pixbuf` the `Pixbuf` to copy options to # Returns `true` on success. Clears a pixbuf to the given RGBA value, converting the RGBA value into the pixbuf's pixel format. The alpha will be ignored if the pixbuf doesn't have an alpha channel. ## `pixel` RGBA pixel to clear to (0xffffffff is opaque white, 0x00000000 transparent black) Flips a pixbuf horizontally or vertically and returns the result in a new pixbuf. ## `horizontal` `true` to flip horizontally, `false` to flip vertically # Returns the new `Pixbuf`, or `None` if not enough memory could be allocated for it. Queries the number of bits per color sample in a pixbuf. # Returns Number of bits per color sample. Returns the length of the pixel data, in bytes. # Returns The length of the pixel data. Queries the color space of a pixbuf. # Returns Color space. Queries whether a pixbuf has an alpha channel (opacity information). # Returns `true` if it has an alpha channel, `false` otherwise. Queries the height of a pixbuf. # Returns Height in pixels. Queries the number of channels of a pixbuf. # Returns Number of channels. Looks up `key` in the list of options that may have been attached to the `self` when it was loaded, or that may have been attached by another function using `Pixbuf::set_option`. For instance, the ANI loader provides "Title" and "Artist" options. The ICO, XBM, and XPM loaders provide "x_hot" and "y_hot" hot-spot options for cursor definitions. The PNG loader provides the tEXt ancillary chunk key/value pairs as options. Since 2.12, the TIFF and JPEG loaders return an "orientation" option string that corresponds to the embedded TIFF/Exif orientation tag (if present). Since 2.32, the TIFF loader sets the "multipage" option string to "yes" when a multi-page TIFF is loaded. Since 2.32 the JPEG and PNG loaders set "x-dpi" and "y-dpi" if the file contains image density information in dots per inch. Since 2.36.6, the JPEG loader sets the "comment" option with the comment EXIF tag. ## `key` a nul-terminated string. # Returns the value associated with `key`. This is a nul-terminated string that should not be freed or `None` if `key` was not found. Returns a `glib::HashTable` with a list of all the options that may have been attached to the `self` when it was loaded, or that may have been attached by another function using `Pixbuf::set_option`. See `Pixbuf::get_option` for more details. Feature: `v2_32` # Returns a `glib::HashTable` of key/values Queries a pointer to the pixel data of a pixbuf. # Returns A pointer to the pixbuf's pixel data. Please see the section on [image data][image-data] for information about how the pixel data is stored in memory. This function will cause an implicit copy of the pixbuf data if the pixbuf was created from read-only data. Queries a pointer to the pixel data of a pixbuf. ## `length` The length of the binary data. # Returns A pointer to the pixbuf's pixel data. Please see the section on [image data][image-data] for information about how the pixel data is stored in memory. This function will cause an implicit copy of the pixbuf data if the pixbuf was created from read-only data. Queries the rowstride of a pixbuf, which is the number of bytes between the start of a row and the start of the next row. # Returns Distance between row starts. Queries the width of a pixbuf. # Returns Width in pixels. Creates a new pixbuf which represents a sub-region of `self`. The new pixbuf shares its pixels with the original pixbuf, so writing to one affects both. The new pixbuf holds a reference to `self`, so `self` will not be finalized until the new pixbuf is finalized. Note that if `self` is read-only, this function will force it to be mutable. ## `src_x` X coord in `self` ## `src_y` Y coord in `self` ## `width` width of region in `self` ## `height` height of region in `self` # Returns a new pixbuf Provides a `glib::Bytes` buffer containing the raw pixel data; the data must not be modified. This function allows skipping the implicit copy that must be made if `Pixbuf::get_pixels` is called on a read-only pixbuf. Feature: `v2_32` # Returns A new reference to a read-only copy of the pixel data. Note that for mutable pixbufs, this function will incur a one-time copy of the pixel data for conversion into the returned `glib::Bytes`. Provides a read-only pointer to the raw pixel data; must not be modified. This function allows skipping the implicit copy that must be made if `Pixbuf::get_pixels` is called on a read-only pixbuf. Feature: `v2_32` # Returns a read-only pointer to the raw pixel data Remove the key/value pair option attached to a `Pixbuf`. Feature: `v2_36` ## `key` a nul-terminated string representing the key to remove. # Returns `true` if an option was removed, `false` if not. Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf. If `angle` is 0, a copy of `self` is returned, avoiding any rotation. ## `angle` the angle to rotate by # Returns the new `Pixbuf`, or `None` if not enough memory could be allocated for it. Modifies saturation and optionally pixelates `self`, placing the result in `dest`. `self` and `dest` may be the same pixbuf with no ill effects. If `saturation` is 1.0 then saturation is not changed. If it's less than 1.0, saturation is reduced (the image turns toward grayscale); if greater than 1.0, saturation is increased (the image gets more vivid colors). If `pixelate` is `true`, then pixels are faded in a checkerboard pattern to create a pixelated image. `self` and `dest` must have the same image format, size, and rowstride. ## `dest` place to write modified version of `self` ## `saturation` saturation factor ## `pixelate` whether to pixelate Saves pixbuf to a file in format `type_`. By default, "jpeg", "png", "ico" and "bmp" are possible file formats to save in, but more formats may be installed. The list of all writable formats can be determined in the following way: ```text void add_if_writable (GdkPixbufFormat *data, GSList **list) { if (gdk_pixbuf_format_is_writable (data)) *list = g_slist_prepend (*list, data); } GSList *formats = gdk_pixbuf_get_formats (); GSList *writable_formats = NULL; g_slist_foreach (formats, add_if_writable, &writable_formats); g_slist_free (formats); ``` If `error` is set, `false` will be returned. Possible errors include those in the `GDK_PIXBUF_ERROR` domain and those in the `G_FILE_ERROR` domain. The variable argument list should be `None`-terminated; if not empty, it should contain pairs of strings that modify the save parameters. For example: ```text gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL); ``` Currently only few parameters exist. JPEG images can be saved with a "quality" parameter; its value should be in the range [0,100]. JPEG and PNG density can be set by setting the "x-dpi" and "y-dpi" parameters to the appropriate values in dots per inch. Text chunks can be attached to PNG images by specifying parameters of the form "tEXt::key", where key is an ASCII string of length 1-79. The values are UTF-8 encoded strings. The PNG compression level can be specified using the "compression" parameter; it's value is in an integer in the range of [0,9]. ICC color profiles can also be embedded into PNG, JPEG and TIFF images. The "icc-profile" value should be the complete ICC profile encoded into base64. ```text gchar *contents; gchar *contents_encode; gsize length; g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL); contents_encode = g_base64_encode ((const guchar *) contents, length); gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL); ``` TIFF images recognize: (1) a "bits-per-sample" option (integer) which can be either 1 for saving bi-level CCITTFAX4 images, or 8 for saving 8-bits per sample; (2) a "compression" option (integer) which can be 1 for no compression, 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for DEFLATE (see the libtiff documentation and tiff.h for all supported codec values); (3) an "icc-profile" option (zero-terminated string) containing a base64 encoded ICC color profile. ICO images can be saved in depth 16, 24, or 32, by using the "depth" parameter. When the ICO saver is given "x_hot" and "y_hot" parameters, it produces a CUR instead of an ICO. ## `filename` name of file to save. ## `type_` name of file format. ## `error` return location for error, or `None` # Returns whether an error was set Saves pixbuf to a new buffer in format `type_`, which is currently "jpeg", "png", "tiff", "ico" or "bmp". This is a convenience function that uses `Pixbuf::save_to_callback` to do the real work. Note that the buffer is not nul-terminated and may contain embedded nuls. If `error` is set, `false` will be returned and `buffer` will be set to `None`. Possible errors include those in the `GDK_PIXBUF_ERROR` domain. See `Pixbuf::save` for more details. ## `buffer` location to receive a pointer to the new buffer. ## `buffer_size` location to receive the size of the new buffer. ## `type_` name of file format. ## `error` return location for error, or `None` # Returns whether an error was set Saves pixbuf to a new buffer in format `type_`, which is currently "jpeg", "tiff", "png", "ico" or "bmp". See `Pixbuf::save_to_buffer` for more details. ## `buffer` location to receive a pointer to the new buffer. ## `buffer_size` location to receive the size of the new buffer. ## `type_` name of file format. ## `option_keys` name of options to set, `None`-terminated ## `option_values` values for named options # Returns whether an error was set Saves pixbuf in format `type_` by feeding the produced data to a callback. Can be used when you want to store the image to something other than a file, such as an in-memory buffer or a socket. If `error` is set, `false` will be returned. Possible errors include those in the `GDK_PIXBUF_ERROR` domain and whatever the save function generates. See `Pixbuf::save` for more details. ## `save_func` a function that is called to save each block of data that the save routine generates. ## `user_data` user data to pass to the save function. ## `type_` name of file format. ## `error` return location for error, or `None` # Returns whether an error was set Saves pixbuf to a callback in format `type_`, which is currently "jpeg", "png", "tiff", "ico" or "bmp". If `error` is set, `false` will be returned. See gdk_pixbuf_save_to_callback () for more details. ## `save_func` a function that is called to save each block of data that the save routine generates. ## `user_data` user data to pass to the save function. ## `type_` name of file format. ## `option_keys` name of options to set, `None`-terminated ## `option_values` values for named options # Returns whether an error was set Saves `self` to an output stream. Supported file formats are currently "jpeg", "tiff", "png", "ico" or "bmp". See `Pixbuf::save_to_buffer` for more details. The `cancellable` can be used to abort the operation from another thread. If the operation was cancelled, the error `gio::IOErrorEnum::Cancelled` will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The stream is not closed. ## `stream` a `gio::OutputStream` to save the pixbuf to ## `type_` name of file format ## `cancellable` optional `gio::Cancellable` object, `None` to ignore ## `error` return location for error, or `None` # Returns `true` if the pixbuf was saved successfully, `false` if an error was set. Saves `self` to an output stream asynchronously. For more details see `Pixbuf::save_to_stream`, which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call `Pixbuf::save_to_stream_finish` to get the result of the operation. ## `stream` a `gio::OutputStream` to which to save the pixbuf ## `type_` name of file format ## `cancellable` optional `gio::Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the pixbuf is saved ## `user_data` the data to pass to the callback function Saves `self` to an output stream. Supported file formats are currently "jpeg", "tiff", "png", "ico" or "bmp". See `Pixbuf::save_to_stream` for more details. Feature: `v2_36` ## `stream` a `gio::OutputStream` to save the pixbuf to ## `type_` name of file format ## `option_keys` name of options to set, `None`-terminated ## `option_values` values for named options ## `cancellable` optional `gio::Cancellable` object, `None` to ignore # Returns `true` if the pixbuf was saved successfully, `false` if an error was set. Saves `self` to an output stream asynchronously. For more details see `Pixbuf::save_to_streamv`, which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call `Pixbuf::save_to_stream_finish` to get the result of the operation. Feature: `v2_36` ## `stream` a `gio::OutputStream` to which to save the pixbuf ## `type_` name of file format ## `option_keys` name of options to set, `None`-terminated ## `option_values` values for named options ## `cancellable` optional `gio::Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the pixbuf is saved ## `user_data` the data to pass to the callback function Saves pixbuf to a file in `type_`, which is currently "jpeg", "png", "tiff", "ico" or "bmp". If `error` is set, `false` will be returned. See gdk_pixbuf_save () for more details. ## `filename` name of file to save. ## `type_` name of file format. ## `option_keys` name of options to set, `None`-terminated ## `option_values` values for named options # Returns whether an error was set Creates a transformation of the source image `self` by scaling by `scale_x` and `scale_y` then translating by `offset_x` and `offset_y`, then renders the rectangle (`dest_x`, `dest_y`, `dest_width`, `dest_height`) of the resulting image onto the destination image replacing the previous contents. Try to use `Pixbuf::scale_simple` first, this function is the industrial-strength power tool you can fall back to if `Pixbuf::scale_simple` isn't powerful enough. If the source rectangle overlaps the destination rectangle on the same pixbuf, it will be overwritten during the scaling which results in rendering artifacts. ## `dest` the `Pixbuf` into which to render the results ## `dest_x` the left coordinate for region to render ## `dest_y` the top coordinate for region to render ## `dest_width` the width of the region to render ## `dest_height` the height of the region to render ## `offset_x` the offset in the X direction (currently rounded to an integer) ## `offset_y` the offset in the Y direction (currently rounded to an integer) ## `scale_x` the scale factor in the X direction ## `scale_y` the scale factor in the Y direction ## `interp_type` the interpolation type for the transformation. Create a new `Pixbuf` containing a copy of `self` scaled to `dest_width` x `dest_height`. Leaves `self` unaffected. `interp_type` should be `InterpType::Nearest` if you want maximum speed (but when scaling down `InterpType::Nearest` is usually unusably ugly). The default `interp_type` should be `InterpType::Bilinear` which offers reasonable quality and speed. You can scale a sub-portion of `self` by creating a sub-pixbuf pointing into `self`; see `Pixbuf::new_subpixbuf`. If `dest_width` and `dest_height` are equal to the `self` width and height, a copy of `self` is returned, avoiding any scaling. For more complicated scaling/alpha blending see `Pixbuf::scale` and `Pixbuf::composite`. ## `dest_width` the width of destination image ## `dest_height` the height of destination image ## `interp_type` the interpolation type for the transformation. # Returns the new `Pixbuf`, or `None` if not enough memory could be allocated for it. Attaches a key/value pair as an option to a `Pixbuf`. If `key` already exists in the list of options attached to `self`, the new value is ignored and `false` is returned. ## `key` a nul-terminated string. ## `value` a nul-terminated string. # Returns `true` on success. The number of bits per sample. Currently only 8 bit per sample are supported. The number of bits per sample. Currently only 8 bit per sample are supported. The number of samples per pixel. Currently, only 3 or 4 samples per pixel are supported. The number of samples per pixel. Currently, only 3 or 4 samples per pixel are supported. The number of bytes between the start of a row and the start of the next row. This number must (obviously) be at least as large as the width of the pixbuf. The number of bytes between the start of a row and the start of the next row. This number must (obviously) be at least as large as the width of the pixbuf. These values can be passed to `gdk_pixbuf_xlib_render_to_drawable_alpha` to control how the alpha channel of an image should be handled. This function can create a bilevel clipping mask (black and white) and use it while painting the image. In the future, when the X Window System gets an alpha channel extension, it will be possible to do full alpha compositing onto arbitrary drawables. For now both cases fall back to a bilevel clipping mask. A bilevel clipping mask (black and white) will be created and used to draw the image. Pixels below 0.5 opacity will be considered fully transparent, and all others will be considered fully opaque. For now falls back to `PixbufAlphaMode::Bilevel`. In the future it will do full alpha compositing. An opaque struct representing an animation. # Implements [`PixbufAnimationExt`](trait.PixbufAnimationExt.html) Trait containing all `PixbufAnimation` methods. # Implementors [`PixbufAnimation`](struct.PixbufAnimation.html), [`PixbufSimpleAnim`](struct.PixbufSimpleAnim.html) Creates a new animation by loading it from a file. The file format is detected automatically. If the file's format does not support multi-frame images, then an animation with a single frame will be created. Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains. ## `filename` Name of file to load, in the GLib file name encoding # Returns A newly-created animation with a reference count of 1, or `None` if any of several error conditions ocurred: the file could not be opened, there was no loader for the file's format, there was not enough memory to allocate the image buffer, or the image file contained invalid data. Creates a new pixbuf animation by loading an image from an resource. The file format is detected automatically. If `None` is returned, then `error` will be set. ## `resource_path` the path of the resource file # Returns A newly-created animation, or `None` if any of several error conditions occurred: the file could not be opened, the image format is not supported, there was not enough memory to allocate the image buffer, the stream contained invalid data, or the operation was cancelled. Creates a new animation by loading it from an input stream. The file format is detected automatically. If `None` is returned, then `error` will be set. The `cancellable` can be used to abort the operation from another thread. If the operation was cancelled, the error `gio::IOErrorEnum::Cancelled` will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The stream is not closed. ## `stream` a `gio::InputStream` to load the pixbuf from ## `cancellable` optional `gio::Cancellable` object, `None` to ignore # Returns A newly-created pixbuf, or `None` if any of several error conditions occurred: the file could not be opened, the image format is not supported, there was not enough memory to allocate the image buffer, the stream contained invalid data, or the operation was cancelled. Finishes an asynchronous pixbuf animation creation operation started with `PixbufAnimation::new_from_stream_async`. ## `async_result` a `gio::AsyncResult` # Returns a `PixbufAnimation` or `None` on error. Free the returned object with `gobject::Object::unref`. Creates a new animation by asynchronously loading an image from an input stream. For more details see `Pixbuf::new_from_stream`, which is the synchronous version of this function. When the operation is finished, `callback` will be called in the main thread. You can then call `PixbufAnimation::new_from_stream_finish` to get the result of the operation. ## `stream` a `gio::InputStream` from which to load the animation ## `cancellable` optional `gio::Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the pixbuf is loaded ## `user_data` the data to pass to the callback function Queries the height of the bounding box of a pixbuf animation. # Returns Height of the bounding box of the animation. Get an iterator for displaying an animation. The iterator provides the frames that should be displayed at a given time. It should be freed after use with `gobject::Object::unref`. `start_time` would normally come from `g_get_current_time`, and marks the beginning of animation playback. After creating an iterator, you should immediately display the pixbuf returned by `PixbufAnimationIterExt::get_pixbuf`. Then, you should install a timeout (with `g_timeout_add`) or by some other mechanism ensure that you'll update the image after `PixbufAnimationIterExt::get_delay_time` milliseconds. Each time the image is updated, you should reinstall the timeout with the new, possibly-changed delay time. As a shortcut, if `start_time` is `None`, the result of `g_get_current_time` will be used automatically. To update the image (i.e. possibly change the result of `PixbufAnimationIterExt::get_pixbuf` to a new frame of the animation), call `PixbufAnimationIterExt::advance`. If you're using `PixbufLoader`, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and `PixbufAnimationIterExt::on_currently_loading_frame` returns `true`. In this case, the frame currently being fed into the loader has received new data, so needs to be refreshed. The delay time for a frame may also be modified after an area_updated signal, for example if the delay time for a frame is encoded in the data after the frame itself. So your timeout should be reinstalled after any area_updated signal. A delay time of -1 is possible, indicating "infinite." ## `start_time` time when the animation starts playing # Returns an iterator to move over the animation If an animation is really just a plain image (has only one frame), this function returns that image. If the animation is an animation, this function returns a reasonable thing to display as a static unanimated image, which might be the first frame, or something more sophisticated. If an animation hasn't loaded any frames yet, this function will return `None`. # Returns unanimated image representing the animation Queries the width of the bounding box of a pixbuf animation. # Returns Width of the bounding box of the animation. If you load a file with `PixbufAnimation::new_from_file` and it turns out to be a plain, unanimated image, then this function will return `true`. Use `PixbufAnimationExt::get_static_image` to retrieve the image. # Returns `true` if the "animation" was really just an image An opaque struct representing an iterator which points to a certain position in an animation. # Implements [`PixbufAnimationIterExt`](trait.PixbufAnimationIterExt.html) Trait containing all `PixbufAnimationIter` methods. # Implementors [`PixbufAnimationIter`](struct.PixbufAnimationIter.html) Possibly advances an animation to a new frame. Chooses the frame based on the start time passed to `PixbufAnimationExt::get_iter`. `current_time` would normally come from `g_get_current_time`, and must be greater than or equal to the time passed to `PixbufAnimationExt::get_iter`, and must increase or remain unchanged each time `PixbufAnimationIterExt::get_pixbuf` is called. That is, you can't go backward in time; animations only play forward. As a shortcut, pass `None` for the current time and `g_get_current_time` will be invoked on your behalf. So you only need to explicitly pass `current_time` if you're doing something odd like playing the animation at double speed. If this function returns `false`, there's no need to update the animation display, assuming the display had been rendered prior to advancing; if `true`, you need to call `PixbufAnimationIterExt::get_pixbuf` and update the display with the new pixbuf. ## `current_time` current time # Returns `true` if the image may need updating Gets the number of milliseconds the current pixbuf should be displayed, or -1 if the current pixbuf should be displayed forever. `g_timeout_add` conveniently takes a timeout in milliseconds, so you can use a timeout to schedule the next update. Note that some formats, like GIF, might clamp the timeout values in the image file to avoid updates that are just too quick. The minimum timeout for GIF images is currently 20 milliseconds. # Returns delay time in milliseconds (thousandths of a second) Gets the current pixbuf which should be displayed; the pixbuf might not be the same size as the animation itself (`PixbufAnimationExt::get_width`, `PixbufAnimationExt::get_height`). This pixbuf should be displayed for `PixbufAnimationIterExt::get_delay_time` milliseconds. The caller of this function does not own a reference to the returned pixbuf; the returned pixbuf will become invalid when the iterator advances to the next frame, which may happen anytime you call `PixbufAnimationIterExt::advance`. Copy the pixbuf to keep it (don't just add a reference), as it may get recycled as you advance the iterator. # Returns the pixbuf to be displayed Used to determine how to respond to the area_updated signal on `PixbufLoader` when loading an animation. area_updated is emitted for an area of the frame currently streaming in to the loader. So if you're on the currently loading frame, you need to redraw the screen for the updated area. # Returns `true` if the frame we're on is partially loaded, or the last frame An error code in the `GDK_PIXBUF_ERROR` domain. Many gdk-pixbuf operations can cause errors in this domain, or in the `G_FILE_ERROR` domain. An image file was broken somehow. Not enough memory. A bad option was passed to a pixbuf save module. Unknown image type. Don't know how to perform the given operation on the type of image at hand. Generic failure code, something went wrong. Only part of the animation was loaded. Creates a copy of `self` # Returns the newly allocated copy of a `PixbufFormat`. Use `PixbufFormat::free` to free the resources when done Frees the resources allocated when copying a `PixbufFormat` using `PixbufFormat::copy` Returns a description of the format. # Returns a description of the format. Returns the filename extensions typically used for files in the given format. # Returns a `None`-terminated array of filename extensions which must be freed with `g_strfreev` when it is no longer needed. Returns information about the license of the image loader for the format. The returned string should be a shorthand for a wellknown license, e.g. "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. This string should be freed with `g_free` when it's no longer needed. # Returns a string describing the license of `self`. Returns the mime types supported by the format. # Returns a `None`-terminated array of mime types which must be freed with `g_strfreev` when it is no longer needed. Returns the name of the format. # Returns the name of the format. Returns whether this image format is disabled. See `PixbufFormat::set_disabled`. # Returns whether this image format is disabled. Returns `true` if the save option specified by `option_key` is supported when saving a pixbuf using the module implementing `self`. See `Pixbuf::save` for more information about option keys. Feature: `v2_36` ## `option_key` the name of an option # Returns `true` if the specified option is supported Returns whether this image format is scalable. If a file is in a scalable format, it is preferable to load it at the desired size, rather than loading it at the default size and scaling the resulting pixbuf to the desired size. # Returns whether this image format is scalable. Returns whether pixbufs can be saved in the given format. # Returns whether pixbufs can be saved in the given format. Disables or enables an image format. If a format is disabled, gdk-pixbuf won't use the image loader for this format to load images. Applications can use this to avoid using image loaders with an inappropriate license, see `PixbufFormat::get_license`. ## `disabled` `true` to disable the format `self` The `PixbufLoader` struct contains only private fields. # Implements [`PixbufLoaderExt`](trait.PixbufLoaderExt.html) Trait containing all `PixbufLoader` methods. # Implementors [`PixbufLoader`](struct.PixbufLoader.html) Creates a new pixbuf loader object. # Returns A newly-created pixbuf loader. Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of mime type `mime_type`, instead of identifying the type automatically. Useful if you want an error if the image isn't the expected mime type, for loading image formats that can't be reliably identified by looking at the data, or if the user manually forces a specific mime type. The list of supported mime types depends on what image loaders are installed, but typically "image/png", "image/jpeg", "image/gif", "image/tiff" and "image/x-xpixmap" are among the supported mime types. To obtain the full list of supported mime types, call `PixbufFormat::get_mime_types` on each of the `PixbufFormat` structs returned by `Pixbuf::get_formats`. ## `mime_type` the mime type to be loaded # Returns A newly-created pixbuf loader. Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of type `image_type`, instead of identifying the type automatically. Useful if you want an error if the image isn't the expected type, for loading image formats that can't be reliably identified by looking at the data, or if the user manually forces a specific type. The list of supported image formats depends on what image loaders are installed, but typically "png", "jpeg", "gif", "tiff" and "xpm" are among the supported formats. To obtain the full list of supported image formats, call `PixbufFormat::get_name` on each of the `PixbufFormat` structs returned by `Pixbuf::get_formats`. ## `image_type` name of the image format to be loaded with the image # Returns A newly-created pixbuf loader. Informs a pixbuf loader that no further writes with `PixbufLoaderExt::write` will occur, so that it can free its internal loading structures. Also, tries to parse any data that hasn't yet been parsed; if the remaining data is partial or corrupt, an error will be returned. If `false` is returned, `error` will be set to an error from the `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains. If you're just cancelling a load rather than expecting it to be finished, passing `None` for `error` to ignore it is reasonable. Remember that this does not unref the loader, so if you plan not to use it anymore, please `gobject::Object::unref` it. # Returns `true` if all image data written so far was successfully passed out via the update_area signal Queries the `PixbufAnimation` that a pixbuf loader is currently creating. In general it only makes sense to call this function after the "area-prepared" signal has been emitted by the loader. If the loader doesn't have enough bytes yet (hasn't emitted the "area-prepared" signal) this function will return `None`. # Returns The `PixbufAnimation` that the loader is loading, or `None` if not enough data has been read to determine the information. Obtains the available information about the format of the currently loading image file. # Returns A `PixbufFormat` or `None`. The return value is owned by `Pixbuf` and should not be freed. Queries the `Pixbuf` that a pixbuf loader is currently creating. In general it only makes sense to call this function after the "area-prepared" signal has been emitted by the loader; this means that enough data has been read to know the size of the image that will be allocated. If the loader has not received enough data via `PixbufLoaderExt::write`, then this function returns `None`. The returned pixbuf will be the same in all future calls to the loader, so simply calling `gobject::Object::ref` should be sufficient to continue using it. Additionally, if the loader is an animation, it will return the "static image" of the animation (see `PixbufAnimationExt::get_static_image`). # Returns The `Pixbuf` that the loader is creating, or `None` if not enough data has been read to determine how to create the image buffer. Causes the image to be scaled while it is loaded. The desired image size can be determined relative to the original size of the image by calling `PixbufLoaderExt::set_size` from a signal handler for the ::size-prepared signal. Attempts to set the desired image size are ignored after the emission of the ::size-prepared signal. ## `width` The desired width of the image being loaded. ## `height` The desired height of the image being loaded. This will cause a pixbuf loader to parse the next `count` bytes of an image. It will return `true` if the data was loaded successfully, and `false` if an error occurred. In the latter case, the loader will be closed, and will not accept further writes. If `false` is returned, `error` will be set to an error from the `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains. ## `buf` Pointer to image data. ## `count` Length of the `buf` buffer in bytes. # Returns `true` if the write was successful, or `false` if the loader cannot parse the buffer. This will cause a pixbuf loader to parse a buffer inside a `glib::Bytes` for an image. It will return `true` if the data was loaded successfully, and `false` if an error occurred. In the latter case, the loader will be closed, and will not accept further writes. If `false` is returned, `error` will be set to an error from the `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains. See also: `PixbufLoaderExt::write` ## `buffer` The image data as a `glib::Bytes` # Returns `true` if the write was successful, or `false` if the loader cannot parse the buffer. This signal is emitted when the pixbuf loader has allocated the pixbuf in the desired size. After this signal is emitted, applications can call `PixbufLoaderExt::get_pixbuf` to fetch the partially-loaded pixbuf. This signal is emitted when a significant area of the image being loaded has been updated. Normally it means that a complete scanline has been read in, but it could be a different area as well. Applications can use this signal to know when to repaint areas of an image that is being loaded. ## `x` X offset of upper-left corner of the updated area. ## `y` Y offset of upper-left corner of the updated area. ## `width` Width of updated area. ## `height` Height of updated area. This signal is emitted when `PixbufLoaderExt::close` is called. It can be used by different parts of an application to receive notification when an image loader is closed by the code that drives it. This signal is emitted when the pixbuf loader has been fed the initial amount of data that is required to figure out the size of the image that it will create. Applications can call `PixbufLoaderExt::set_size` in response to this signal to set the desired size to which the image should be scaled. ## `width` the original width of the image ## `height` the original height of the image The possible rotations which can be passed to `Pixbuf::rotate_simple`. To make them easier to use, their numerical values are the actual degrees. No rotation. Rotate by 90 degrees. Rotate by 180 degrees. Rotate by 270 degrees. An opaque struct representing a simple animation. # Implements [`PixbufAnimationExt`](trait.PixbufAnimationExt.html) Creates a new, empty animation. ## `width` the width of the animation ## `height` the height of the animation ## `rate` the speed of the animation, in frames per second # Returns a newly allocated `PixbufSimpleAnim` Adds a new frame to `self`. The `pixbuf` must have the dimensions specified when the animation was constructed. ## `pixbuf` the pixbuf to add Gets whether `self` should loop indefinitely when it reaches the end. # Returns `true` if the animation loops forever, `false` otherwise Sets whether `self` should loop indefinitely when it reaches the end. ## `loop_` whether to loop the animation Whether the animation should loop when it reaches the end. Whether the animation should loop when it reaches the end. gtk-rs-lgpl-docs-0.1.12/gdk/docs.md010064400007650000024000000000201350370316300151130ustar0000000000000000 gtk-rs-lgpl-docs-0.1.12/gdk/vendor.md010064400007650000024000007005731350423663000155050ustar0000000000000000 `AppLaunchContext` is an implementation of `gio::AppLaunchContext` that handles launching an application in a graphical context. It provides startup notification and allows to launch applications on a specific screen or workspace. ## Launching an application ```C GdkAppLaunchContext *context; context = gdk_display_get_app_launch_context (display); gdk_app_launch_context_set_screen (screen); gdk_app_launch_context_set_timestamp (event->time); if (!g_app_info_launch_default_for_uri ("http://www.gtk.org", context, &error)) g_warning ("Launching failed: %s\n", error->message); g_object_unref (context); ``` # Implements [`gio::AppLaunchContextExt`](../gio/trait.AppLaunchContextExt.html) Sets the workspace on which applications will be launched when using this context when running under a window manager that supports multiple workspaces, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec). When the workspace is not specified or `desktop` is set to -1, it is up to the window manager to pick one, typically it will be the current workspace. ## `desktop` the number of a workspace, or -1 Sets the icon for applications that are launched with this context. Window Managers can use this information when displaying startup notification. See also `AppLaunchContext::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`. If both `icon` and `icon_name` are set, the `icon_name` takes priority. If neither `icon` or `icon_name` is set, the icon is taken from either the file that is passed to launched application or from the `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`. 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. Window managers can use this information to avoid moving the focus to the newly launched application when the user is busy typing in another window. This is also known as 'focus stealing prevention'. ## `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. the axis is used as the x axis. the axis is used as the y axis. the axis is used for pressure information. the axis is used for x tilt information. the axis is used for y tilt information. the axis is used for wheel information. the axis is used for pen/tablet distance information. (Since: 3.22) the axis is used for pen rotation information. (Since: 3.22) the axis is used for pen slider information. (Since: 3.22) a constant equal to the numerically highest axis value. A set of values describing the possible byte-orders for storing pixel values in memory. The values are stored with the least-significant byte first. For instance, the 32-bit value 0xffeecc would be stored in memory as 0xcc, 0xee, 0xff, 0x00. The values are stored with the most-significant byte first. For instance, the 32-bit value 0xffeecc would be stored in memory as 0x00, 0xff, 0xee, 0xcc. Specifies the crossing mode for `EventCrossing`. crossing because of pointer motion. crossing because a grab is activated. crossing because a grab is deactivated. crossing because a GTK+ grab is activated. crossing because a GTK+ grab is deactivated. crossing because a GTK+ widget changed state (e.g. sensitivity). crossing because a touch sequence has begun, this event is synthetic as the pointer might have not left the window. crossing because a touch sequence has ended, this event is synthetic as the pointer might have not left the window. crossing because of a device switch (i.e. a mouse taking control of the pointer after a touch device), this event is synthetic as the pointer didn’t leave the window. A `Cursor` represents a cursor. Its contents are private. Creates a new cursor from the set of builtin cursors for the default display. See `Cursor::new_for_display`. To make the cursor invisible, use `CursorType::BlankCursor`. # Deprecated since 3.16 Use `Cursor::new_for_display` instead. ## `cursor_type` cursor to create # Returns a new `Cursor` Creates a new cursor from the set of builtin cursors. ## `display` the `Display` for which the cursor will be created ## `cursor_type` cursor to create # Returns 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` the name of the cursor # Returns a new `Cursor`, or `None` if there is no cursor with the given name 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 whether RGBA cursors are supported; `Display::get_default_cursor_size` and `Display::get_maximal_cursor_size` give information about cursor sizes. If `x` or `y` are `-1`, the pixbuf must have options named “x_hot” and “y_hot”, resp., containing integer values between `0` and the width resp. height of the pixbuf. (Since: 3.0) On the X backend, support for RGBA cursors requires a sufficently new version of the X Render extension. ## `display` the `Display` for which the cursor will be created ## `pixbuf` the `gdk_pixbuf::Pixbuf` containing the cursor image ## `x` the horizontal offset of the “hotspot” of the cursor. ## `y` the vertical offset of the “hotspot” of the cursor. # Returns a new `Cursor`. Creates a new cursor from a cairo image surface. Not all GDK backends support RGBA cursors. If they are not supported, a monochrome approximation will be displayed. The functions `Display::supports_cursor_alpha` and `Display::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 cursor sizes. On the X backend, support for RGBA cursors requires a sufficently new version of the X Render extension. ## `display` the `Display` for which the cursor will be created ## `surface` the cairo image surface containing the cursor pixel data ## `x` the horizontal offset of the “hotspot” of the cursor ## `y` 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 on the cursor, GDK may not be able to obtain the image data. In this case, `None` is returned. # Returns 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 on the cursor, GDK may not be able to obtain the image data. In this case, `None` is returned. ## `x_hot` Location to store the hotspot x position, or `None` ## `y_hot` Location to store the hotspot y position, or `None` # Returns a `cairo::Surface` representing `self`, or `None` 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) ![](arrow.png) ![](based_arrow_down.png) ![](based_arrow_up.png) ![](boat.png) ![](bogosity.png) ![](bottom_left_corner.png) ![](bottom_right_corner.png) ![](bottom_side.png) ![](bottom_tee.png) ![](box_spiral.png) ![](center_ptr.png) ![](circle.png) ![](clock.png) ![](coffee_mug.png) ![](cross.png) ![](cross_reverse.png) ![](crosshair.png) ![](diamond_cross.png) ![](dot.png) ![](dotbox.png) ![](double_arrow.png) ![](draft_large.png) ![](draft_small.png) ![](draped_box.png) ![](exchange.png) ![](fleur.png) ![](gobbler.png) ![](gumby.png) ![](hand1.png) ![](hand2.png) ![](heart.png) ![](icon.png) ![](iron_cross.png) ![](left_ptr.png) ![](left_side.png) ![](left_tee.png) ![](leftbutton.png) ![](ll_angle.png) ![](lr_angle.png) ![](man.png) ![](middlebutton.png) ![](mouse.png) ![](pencil.png) ![](pirate.png) ![](plus.png) ![](question_arrow.png) ![](right_ptr.png) ![](right_side.png) ![](right_tee.png) ![](rightbutton.png) ![](rtl_logo.png) ![](sailboat.png) ![](sb_down_arrow.png) ![](sb_h_double_arrow.png) ![](sb_left_arrow.png) ![](sb_right_arrow.png) ![](sb_up_arrow.png) ![](sb_v_double_arrow.png) ![](shuttle.png) ![](sizing.png) ![](spider.png) ![](spraycan.png) ![](star.png) ![](target.png) ![](tcross.png) ![](top_left_arrow.png) ![](top_left_corner.png) ![](top_right_corner.png) ![](top_side.png) ![](top_tee.png) ![](trek.png) ![](ul_angle.png) ![](umbrella.png) ![](ur_angle.png) ![](watch.png) ![](xterm.png) last cursor type Blank cursor. Since 2.16 type of cursors constructed with `Cursor::new_from_pixbuf` The `Device` object represents a single input device, such 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. Frees an array of `TimeCoord` that was returned by `Device::get_history`. ## `events` an array of `TimeCoord`. ## `n_events` the length of the array. Determines information about the current keyboard grab. This is not public API and must not be used by applications. # Deprecated since 3.16 The symbol was never meant to be used outside of GTK+ ## `display` the display for which to get the grab information ## `device` device to get the grab information from ## `grab_window` location to store current grab window ## `owner_events` location to store boolean indicating whether the `owner_events` flag to `gdk_keyboard_grab` or `gdk_pointer_grab` was `true`. # Returns `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. If `self` is of type `DeviceType::Slave`, it will return the master device to which `self` is attached to. If `self` is of type `DeviceType::Floating`, `None` will be returned, as there is no associated device. # Returns 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` pointer to an array of axes ## `use_` the use to look for ## `value` 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. # 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` ## `axes` pointer to an array of axes ## `axis_label` `Atom` with the axis label. ## `value` 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 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 `WindowExt::set_event_compression` to get more motion events delivered directly, independent of the windowing system. ## `window` the window with respect to which which the event coordinates will be reported ## `start` starting timestamp for range of events to return ## `stop` ending timestamp for the range of events to return ## `events` location to store a newly-allocated array of `TimeCoord`, or `None` ## `n_events` location to store the length of `events`, or `None` # Returns `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_` the index of the macro button to get. ## `keyval` return value for the keyval. ## `modifiers` 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`, `None` may be returned even if the pointer is physically over one of this application's windows. # 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`. ## `screen` location to store the `Screen` the `self` is on, or `None`. ## `x` 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`. ## `screen` location to store the `Screen` the `self` is on, or `None`. ## `x` 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. 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`. ## `window` a `Window`. ## `axes` 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. compose `gio::Settings` paths to store settings for this device. ```C static GSettings * get_device_settings (GdkDevice *device) { const gchar *vendor, *product; GSettings *settings; GdkDevice *device; gchar *path; vendor = gdk_device_get_vendor_id (device); product = gdk_device_get_product_id (device); path = g_strdup_printf ("/org/example/app/devices/%s:%s/", vendor, product); settings = g_settings_new_with_path (DEVICE_SCHEMA, path); g_free (path); return settings; } ``` 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`. ## `win_x` return location for the X coordinate of the device location, relative to the window origin, or `None`. ## `win_y` return location for the Y coordinate of the device location, relative to the window origin, or `None`. # Returns 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`. ## `win_x` return location for the X coordinate of the device location, relative to the window origin, or `None`. ## `win_y` return location for the Y coordinate of the device location, relative to the window origin, or `None`. # Returns 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`, or the window becomes unviewable. This overrides any previous grab on the device by this client. Note that `self` and `window` need to be on the same display. Device grabs are used for operations which need complete control over the given device events (either pointer or keyboard). For example in GTK+ this is used for Drag and Drop operations, popup menus and such. Note that if the event mask of an X window has selected both button press and button release events, then a button press event will cause an automatic pointer grab until the button is released. X does this automatically since most applications expect to receive button press and release events in pairs. It is equivalent to a pointer grab on the window with `owner_events` set to `true`. If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the `EventGrabBroken` events that are emitted when the grab ends unvoluntarily. # Deprecated since 3.20 Use `Seat::grab` instead. ## `window` the `Window` which will own the grab (the grab window) ## `grab_ownership` specifies the grab ownership. ## `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. ## `event_mask` specifies the event mask, which is used in accordance with `owner_events`. ## `cursor` the cursor to display while the grab is active if the device is a pointer. If this is `None` then the normal cursors are used for `window` and its descendants, and the cursor for `window` is used elsewhere. ## `time_` the timestamp of the event which led to this pointer grab. This usually comes from the ``GdkEvent`` struct, though `GDK_CURRENT_TIME` can be used if the time isn’t known. # Returns `GrabStatus::Success` if the grab was successful. Returns a `glib::List` of ``GdkAtoms``, containing the labels for the axes that `self` currently has. # Returns 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` # Returns 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_` the index of the macro button to set ## `keyval` 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. Note: This is only meaningful for floating devices, master devices (and slaves connected to these) drive the pointer cursor, which is not limited by the input mode. ## `mode` the input mode. # Returns `true` if the mode was successfully changed. Release any grab on `self`. # Deprecated since 3.20 Use `Seat::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 as far as allowed by the grab. Warping the pointer creates events as if the user had moved the mouse instantaneously to the destination. Note that the pointer should normally be under the control of the user. This function was added to cover some rare use cases like keyboard navigation support for the color picker in the ``GtkColorSelectionDialog``. ## `screen` the screen to warp `self` to. ## `x` the X coordinate of the destination. ## `y` the Y coordinate of the destination. The ::changed signal is emitted either when the `Device` has changed the number of either axes or keys. For example In X this will normally happen when the slave device routing events through the master device changes (for example, user switches from the USB mouse to a tablet), in that case the master device will change to reflect the new slave device axes and keys. The ::tool-changed signal is emitted on pen/eraser ``GdkDevices`` whenever tools enter or leave proximity. Feature: `v3_22` ## `tool` The new current tool Associated pointer or keyboard with this device, if any. Devices of type `DeviceType::Master` always come in keyboard/pointer pairs. Other device types will have a `None` associated device. The axes currently available for this device. Feature: `v3_22` The `DeviceManager` the `Device` pertains to. The `DeviceManager` the `Device` pertains to. The `Display` the `Device` pertains to. The `Display` the `Device` pertains to. Whether the device is represented by a cursor on the screen. Devices of type `DeviceType::Master` will have `true` here. Whether the device is represented by a cursor on the screen. Devices of type `DeviceType::Master` will have `true` here. Source type for the device. Source type for the device. Number of axes in the device. The device name. The device name. The maximal number of concurrent touches on a touch device. Will be 0 if the device is not a touch device or if the number of touches is unknown. Feature: `v3_20` The maximal number of concurrent touches on a touch device. Will be 0 if the device is not a touch device or if the number of touches is unknown. Feature: `v3_20` Product ID of this device, see `Device::get_product_id`. Feature: `v3_16` Product ID of this device, see `Device::get_product_id`. Feature: `v3_16` `Seat` of this device. Feature: `v3_20` `Seat` of this device. Feature: `v3_20` Device role in the device manager. Device role in the device manager. Vendor ID of this device, see `Device::get_vendor_id`. Feature: `v3_16` Vendor ID of this device, see `Device::get_vendor_id`. Feature: `v3_16` In addition to a single pointer and keyboard for user interface input, GDK contains support for a variety of input devices, including graphics tablets, touchscreens and multiple pointers/keyboards interacting simultaneously with the user interface. Such input devices often have additional features, such as sub-pixel positioning information and additional device-dependent information. In order to query the device hierarchy and be aware of changes in the device hierarchy (such as virtual devices being created or removed, or physical devices being plugged or unplugged), GDK provides `DeviceManager`. By default, and if the platform supports it, GDK is aware of multiple keyboard/pointer pairs and multitouch devices. This behavior can be changed by calling `gdk_disable_multidevice` before `Display::open`. There should rarely be a need to do that though, since GDK defaults to a compatibility mode in which it will emit just one enter/leave event pair for all devices on a window. To enable per-device enter/leave events and other multi-pointer interaction features, `WindowExt::set_support_multidevice` must be called on ``GdkWindows`` (or `gtk_widget_set_support_multidevice` on widgets). window. See the `WindowExt::set_support_multidevice` documentation for more information. On X11, multi-device support is implemented through XInput 2. Unless `gdk_disable_multidevice` is called, the XInput 2 `DeviceManager` implementation will be used as the input source. Otherwise either the core or XInput 1 implementations will be used. For simple applications that don’t have any special interest in input devices, the so-called “client pointer” provides a reasonable approximation to a simple setup with a single pointer and keyboard. The device that has been set as the client pointer can be accessed via `DeviceManager::get_client_pointer`. Conceptually, in multidevice mode there are 2 device types. Virtual devices (or master devices) are represented by the pointer cursors and keyboard foci that are seen on the screen. Physical devices (or slave devices) represent the hardware that is controlling the virtual devices, and thus have no visible cursor on the screen. Virtual devices are always paired, so there is a keyboard device for every pointer device. Associations between devices may be inspected through `Device::get_associated_device`. There may be several virtual devices, and several physical devices could be controlling each of these virtual devices. Physical devices may also be “floating”, which means they are not attached to any virtual device. # Master and slave devices ```text carlos@sacarino:~$ xinput list ⎡ Virtual core pointer id=2 [master pointer (3)] ⎜ ↳ Virtual core XTEST pointer id=4 [slave pointer (2)] ⎜ ↳ Wacom ISDv4 E6 Pen stylus id=10 [slave pointer (2)] ⎜ ↳ Wacom ISDv4 E6 Finger touch id=11 [slave pointer (2)] ⎜ ↳ SynPS/2 Synaptics TouchPad id=13 [slave pointer (2)] ⎜ ↳ TPPS/2 IBM TrackPoint id=14 [slave pointer (2)] ⎜ ↳ Wacom ISDv4 E6 Pen eraser id=16 [slave pointer (2)] ⎣ Virtual core keyboard id=3 [master keyboard (2)] ↳ Virtual core XTEST keyboard id=5 [slave keyboard (3)] ↳ Power Button id=6 [slave keyboard (3)] ↳ Video Bus id=7 [slave keyboard (3)] ↳ Sleep Button id=8 [slave keyboard (3)] ↳ Integrated Camera id=9 [slave keyboard (3)] ↳ AT Translated Set 2 keyboard id=12 [slave keyboard (3)] ↳ ThinkPad Extra Buttons id=15 [slave keyboard (3)] ``` By default, GDK will automatically listen for events coming from all master devices, setting the `Device` for all events coming from input devices. Events containing device information are `EventType::MotionNotify`, `EventType::ButtonPress`, `EventType::2buttonPress`, `EventType::3buttonPress`, `EventType::ButtonRelease`, `EventType::Scroll`, `EventType::KeyPress`, `EventType::KeyRelease`, `EventType::EnterNotify`, `EventType::LeaveNotify`, `EventType::FocusChange`, `EventType::ProximityIn`, `EventType::ProximityOut`, `EventType::DragEnter`, `EventType::DragLeave`, `EventType::DragMotion`, `EventType::DragStatus`, `EventType::DropStart`, `EventType::DropFinished` and `EventType::GrabBroken`. When dealing with an event on a master device, it is possible to get the source (slave) device that the event originated from via `gdk_event_get_source_device`. On a standard session, all physical devices are connected by default to the "Virtual Core Pointer/Keyboard" master devices, hence routing all events through these. This behavior is only modified by device grabs, where the slave device is temporarily detached for as long as the grab is held, and more permanently by user modifications to the device hierarchy. On certain application specific setups, it may make sense to detach a physical device from its master pointer, and mapping it to an specific window. This can be achieved by the combination of `Device::grab` and `Device::set_mode`. In order to listen for events coming from devices 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 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. 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`. In GTK+ 3.20, a new `Seat` object has been introduced that supersedes `DeviceManager` and should be preferred in newly written code. Returns the client pointer, that is, the master pointer that acts as the core pointer for this application. In X11, window managers may change this depending on the interaction pattern under the presence of several pointers. You should use this function seldomly, only in code that isn’t triggered by a ``GdkEvent`` and there aren’t other means to get a meaningful `Device` to operate on. # Deprecated since 3.20 Use `Seat::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 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 `Seat::get_pointer`, `Seat::get_keyboard` and `Seat::get_slaves` instead. ## `type_` device type to get. # Returns 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. The ::device-added signal is emitted either when a new master pointer is created, or when a slave (Hardware) input device is plugged in. ## `device` the newly added `Device`. The ::device-changed signal is emitted whenever a device has changed in the hierarchy, either slave devices being disconnected from their master device or connected to another one, or master devices being added or removed a slave device. If a slave device is detached from all master devices (`Device::get_associated_device` returns `None`), its `DeviceType` will change to `DeviceType::Floating`, if it's attached, it will change to `DeviceType::Slave`. ## `device` the `Device` that changed. The ::device-removed signal is emitted either when a master pointer is removed, or when a slave (Hardware) input device is unplugged. ## `device` the just removed `Device`. `DevicePad` is an interface implemented by devices of type `InputSource::TabletPad`, it allows querying the features provided by the pad device. Tablet pads may contain one or more groups, each containing a subset of the buttons/rings/strips available. `DevicePad::get_n_groups` can be used to obtain the number of groups, `DevicePad::get_n_features` and `DevicePad::get_feature_group` can be combined to find out the number of buttons/rings/strips the device has, and how are they grouped. Each of those groups have different modes, which may be used to map each individual pad feature to multiple actions. Only one mode is effective (current) for each given group, different groups may have different current modes. The number of available modes in a group can be found out through `DevicePad::get_group_n_modes`, and the current mode for a given group will be notified through the `EventPadGroupMode` event. Feature: `v3_22` # Implements [`DevicePadExt`](trait.DevicePadExt.html), [`DeviceExt`](trait.DeviceExt.html) Trait containing all `DevicePad` methods. Feature: `v3_22` # Implementors [`DevicePad`](struct.DevicePad.html) Returns the group the given `feature` and `idx` belong to, or -1 if feature/index do not exist in `self`. Feature: `v3_22` ## `feature` the feature type to get the group from ## `feature_idx` the index of the feature to get the group from # Returns The group number of the queried pad feature. Returns the number of modes that `group` may have. Feature: `v3_22` ## `group_idx` group to get the number of available modes from # Returns The number of modes available in `group`. Returns the number of features a tablet pad has. Feature: `v3_22` ## `feature` a pad feature # Returns The amount of elements of type `feature` that this pad has. Returns the number of groups this pad device has. Pads have at least one group. A pad group is a subcollection of buttons/strip/rings that is affected collectively by a same current mode. Feature: `v3_22` # Returns The number of button/ring/strip groups in the pad. A pad feature. a button a ring-shaped interactive area a straight interactive area Feature: `v3_22` 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 `DeviceTool::get_serial`). This is a more concrete (and device specific) method to identify a `DeviceTool` than `DeviceTool::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. Device is a master (or virtual) device. There will be an associated focus indicator on the screen. Device is a slave (or physical) device. Device is a physical device, currently not attached to any virtual device. `Display` objects purpose are two fold: - To manage and provide information about input devices (pointers and keyboards) - To manage and provide information about the available ``GdkScreens`` `Display` objects are the GDK representation of an X Display, which can be described as a workstation consisting of a keyboard, a pointing device (such as a mouse) and one or more screens. It is used to open and keep track of various `Screen` objects currently instantiated by the application. It is also used to access the keyboard(s) and mouse pointer(s) of the display. Most of the input device handling has been factored out into the separate `DeviceManager` object. Every display has a device manager, which you can obtain using `Display::get_device_manager`. Gets the default `Display`. This is a convenience function for: `gdk_display_manager_get_default_display (gdk_display_manager_get ())`. # Returns a `Display`, or `None` if there is no default display. Opens a display. ## `display_name` the name of the display to open # Returns a `Display`, or `None` if the display could not be opened Opens the default display specified by command line arguments or environment variables, sets it as the default display, and returns it. `gdk_parse_args` must have been called first. If the default display has previously been set, simply returns that. An internal function that should not be used by applications. # Deprecated since 3.16 This symbol was never meant to be used outside of GTK+ # Returns 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` # 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 to call this function explicitly. A common case where this function needs to be called is when an application is executing drawing commands from a thread other than the thread where the main loop is running. This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing. Returns a `AppLaunchContext` suitable for launching applications on the given display. # Returns 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 `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 `Display::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. # Returns 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 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 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 `Display::get_default_screen` to get it. ## `screen_num` the screen number # Returns the `Screen` object 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. 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. GTK+ will call this function automatically for ``GtkWindow`` with custom startup-notification identifier unless `gtk_window_set_auto_startup_notification` is called to disable that feature. ## `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 that have already been moved to the GDK event queue.) # Returns 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`. 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` the `Atom` naming the selection for which ownership change notification is requested # Returns 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`. 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 [FreeDesktop Clipboard Specification](http://www.freedesktop.org/Standards/clipboard-manager-spec). ## `clipboard_window` a `Window` belonging to the clipboard owner ## `time_` a timestamp ## `targets` an array of targets that should be saved, or `None` 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 running. # Returns `true` if the display supports clipboard persistance. 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 XDamage extensions available. # Deprecated since 3.16 Compositing is an outdated technology that only ever worked on X11. # 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). # 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. # 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. # Returns 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 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. The ::closed signal is emitted when the connection to the windowing system for `display` is closed. ## `is_error` `true` if the display was closed due to an error The ::monitor-added signal is emitted whenever a monitor is added. Feature: `v3_22` ## `monitor` the monitor that was just added The ::monitor-removed signal is emitted whenever a monitor is removed. Feature: `v3_22` ## `monitor` the monitor that was just removed The ::opened signal is emitted when the connection to the windowing system for `display` is opened. The ::seat-added signal is emitted whenever a new seat is made known to the windowing system. Feature: `v3_20` ## `seat` the seat that was just added The ::seat-removed signal is emitted whenever a seat is removed by the windowing system. Feature: `v3_20` ## `seat` the seat that was just removed The purpose of the `DisplayManager` singleton object is to offer notification when displays appear or disappear or the default display changes. You can use `DisplayManager::get` to obtain the `DisplayManager` singleton, but that should be rarely necessary. Typically, initializing GTK+ opens a display that you can work with without ever accessing the `DisplayManager`. The GDK library can be built with support for multiple backends. The `DisplayManager` object determines which backend is used at runtime. When writing backend-specific code that is supposed to work with multiple GDK backends, you have to consider both compile time and runtime. At compile time, use the `GDK_WINDOWING_X11`, `GDK_WINDOWING_WIN32` macros, etc. to find out which backends are present in the GDK library you are building your application against. At runtime, use type-check macros like GDK_IS_X11_DISPLAY() to find out which backend is in use: ## Backend-specific code ## {`backend`-specific} ```C #ifdef GDK_WINDOWING_X11 if (GDK_IS_X11_DISPLAY (display)) { // make X11-specific calls here } else #endif #ifdef GDK_WINDOWING_QUARTZ if (GDK_IS_QUARTZ_DISPLAY (display)) { // make Quartz-specific calls here } else #endif g_error ("Unsupported GDK backend"); ``` Gets the singleton `DisplayManager` object. When called for the first time, this function consults the `GDK_BACKEND` environment variable to find out which of the supported GDK backends to use (in case GDK has been compiled with multiple backends). Applications can use `gdk_set_allowed_backends` to limit what backends can be used. # Returns 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 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 # Returns a `Display`, or `None` if the display could not be opened Sets `display` as the default display. ## `display` a `Display` The ::display-opened signal is emitted when a display is opened. ## `display` the opened 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` Determines the bitmask of actions proposed by the source if `DragContext::get_suggested_action` returns `DragAction::Ask`. # Returns the `DragAction` flags Returns the destination window 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 that is 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 A new action is being chosen for the drag and drop operation. This signal will only be emitted if the `DragContext` manages the drag and drop operation. See `DragContext::manage_dnd` for more information. Feature: `v3_20` ## `action` The action currently chosen The drag and drop operation was cancelled. This signal will only be emitted if the `DragContext` manages the drag and drop operation. See `DragContext::manage_dnd` for more information. Feature: `v3_20` ## `reason` The reason the context was cancelled The drag and drop operation was finished, the drag destination finished reading all data. The drag source can now free all miscellaneous data. This signal will only be emitted if the `DragContext` manages the drag and drop operation. See `DragContext::manage_dnd` for more information. Feature: `v3_20` The drag and drop operation was performed on an accepting client. This signal will only be emitted if the `DragContext` manages the drag and drop operation. See `DragContext::manage_dnd` for more information. Feature: `v3_20` ## `time` the time at which the drop happened. Used in `DragContext` to indicate the protocol according to which DND is done. no protocol. The Motif DND protocol. No longer supported The Xdnd protocol. An extension to the Xdnd protocol for unclaimed root window drops. The simple WM_DROPFILES protocol. The complex OLE2 DND protocol (not implemented). Intra-application DND. Wayland DND protocol. `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` 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 The clip region applied to the drawing context. Feature: `v3_22` The clip region applied to the drawing context. Feature: `v3_22` The `Window` that created the drawing context. Feature: `v3_22` The `Window` that created the drawing context. Feature: `v3_22` Contains the fields which are common to all event structs. Any event pointer can safely be cast to a pointer to a `EventAny` to access these fields. Used for button press and button release events. The `type` field will be one of `EventType::ButtonPress`, `EventType::2buttonPress`, `EventType::3buttonPress` or `EventType::ButtonRelease`, Double and triple-clicks result in a sequence of events being received. For double-clicks the order of events will be: - `EventType::ButtonPress` - `EventType::ButtonRelease` - `EventType::ButtonPress` - `EventType::2buttonPress` - `EventType::ButtonRelease` Note that the first click is received just like a normal button press, while the second click results in a `EventType::2buttonPress` being received just after the `EventType::ButtonPress`. Triple-clicks are very similar to double-clicks, except that `EventType::3buttonPress` is inserted after the third click. The order of the events is: - `EventType::ButtonPress` - `EventType::ButtonRelease` - `EventType::ButtonPress` - `EventType::2buttonPress` - `EventType::ButtonRelease` - `EventType::ButtonPress` - `EventType::3buttonPress` - `EventType::ButtonRelease` For a double click to occur, the second button press must occur within 1/4 of a second of the first. For a triple click to occur, the third button press must also occur within 1/2 second of the first button press. Generated when a window size or position has changed. Generated when the pointer enters or leaves a window. Generated during DND operations. Generated when all or part of a window becomes visible and needs to be redrawn. Describes a change of keyboard focus. Generated when a pointer or keyboard grab is broken. On X11, this happens when the grab window becomes unviewable (i.e. it or one of its ancestors is unmapped), or if the same application grabs the pointer or keyboard again. Note that implicit grabs (which are initiated by button presses) can also cause `EventGrabBroken` events. Describes a key press or key release event. Generated when the pointer moves. Generated when the owner of a selection changes. On X11, this information is only available if the X server supports the XFIXES extension. Generated during `InputSource::TabletPad` interaction with tactile sensors. Feature: `v3_22` Generated during `InputSource::TabletPad` button presses and releases. Feature: `v3_22` Generated during `InputSource::TabletPad` mode switches in a group. Feature: `v3_22` Describes a property change on a window. Proximity events are generated when using GDK’s wrapper for the XInput extension. The XInput extension is an add-on for standard X that allows you to use nonstandard devices such as graphics tablets. A proximity event indicates that the stylus has moved in or out of contact with the tablet, or perhaps that the user’s finger has moved in or out of contact with a touch screen. This event type will be used pretty rarely. It only is important for XInput aware programs that are drawing their own cursor. Generated from button presses for the buttons 4 to 7. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned. Some GDK backends can also generate “smooth” scroll events, which can be recognized by the `ScrollDirection::Smooth` scroll direction. For these, the scroll deltas can be obtained with `gdk_event_get_scroll_deltas`. Generated when a selection is requested or ownership of a selection is taken over by another client application. Generated when a setting is modified. Used for touch events. `type` field will be one of `EventType::TouchBegin`, `EventType::TouchUpdate`, `EventType::TouchEnd` or `EventType::TouchCancel`. Touch events are grouped into sequences by means of the `sequence` field, which can also be obtained with `gdk_event_get_event_sequence`. Each sequence begins with a `EventType::TouchBegin` event, followed by any number of `EventType::TouchUpdate` events, and ends with a `EventType::TouchEnd` (or `EventType::TouchCancel`) event. With multitouch devices, there may be several active sequences at the same time. Generated during touchpad swipe gestures. Generated during touchpad swipe gestures. Specifies the type of the event. Do not confuse these events with the signals that GTK+ widgets emit. Although many of these events result in corresponding signals being emitted, the events are often transformed or filtered along the way. In some language bindings, the values `EventType::2buttonPress` and `EventType::3buttonPress` would translate into something syntactically invalid (eg `Gdk.EventType.2ButtonPress`, where a symbol is not allowed to start with a number). In that case, the aliases `EventType::DoubleButtonPress` and `EventType::TripleButtonPress` can be used instead. a special code to indicate a null event. the window manager has requested that the toplevel window be hidden or destroyed, usually when the user clicks on a special icon in the title bar. the window has been destroyed. all or part of the window has become visible and needs to be redrawn. the pointer (usually a mouse) has moved. a mouse button has been pressed. a mouse button has been double-clicked (clicked twice within a short period of time). Note that each click also generates a `EventType::ButtonPress` event. alias for `EventType::2buttonPress`, added in 3.6. a mouse button has been clicked 3 times in a short period of time. Note that each click also generates a `EventType::ButtonPress` event. alias for `EventType::3buttonPress`, added in 3.6. a mouse button has been released. a key has been pressed. a key has been released. the pointer has entered the window. the pointer has left the window. the keyboard focus has entered or left the window. the size, position or stacking order of the window has changed. Note that GTK+ discards these events for `WindowType::Child` windows. the window has been mapped. the window has been unmapped. a property on the window has been changed or deleted. the application has lost ownership of a selection. another application has requested a selection. a selection has been received. an input device has moved into contact with a sensing surface (e.g. a touchscreen or graphics tablet). an input device has moved out of contact with a sensing surface. the mouse has entered the window while a drag is in progress. the mouse has left the window while a drag is in progress. the mouse has moved in the window while a drag is in progress. the status of the drag operation initiated by the window has changed. a drop operation onto the window has started. the drop operation initiated by the window has completed. a message has been received from another application. the window visibility status has changed. the scroll wheel was turned the state of a window has changed. See `WindowState` for the possible window states a setting has been modified. the owner of a selection has changed. This event type was added in 2.6 a pointer or keyboard grab was broken. This event type was added in 2.8. the content of the window has been changed. This event type was added in 2.14. A new touch event sequence has just started. This event type was added in 3.4. A touch event sequence has been updated. This event type was added in 3.4. A touch event sequence has finished. This event type was added in 3.4. A touch event sequence has been canceled. This event type was added in 3.4. A touchpad swipe gesture event, the current state is determined by its phase field. This event type was added in 3.18. A touchpad pinch gesture event, the current state is determined by its phase field. This event type was added in 3.18. A tablet pad button press event. This event type was added in 3.22. A tablet pad button release event. This event type was added in 3.22. A tablet pad axis event from a "ring". This event type was added in 3.22. A tablet pad axis event from a "strip". This event type was added in 3.22. A tablet pad group mode change. This event type was added in 3.22. marks the end of the `EventType` enumeration. Added in 2.18 Generated when the state of a toplevel window changes. A `FrameClock` tells the application when to update and repaint a window. This may be synced to the vertical refresh rate of the monitor, for example. Even when the frame clock uses a simple timer rather than a hardware-based vertical sync, the frame clock helps because it ensures everything paints at the same time (reducing the total number of frames). The frame clock can also automatically stop painting when it knows the frames will not be visible, or scale back animation framerates. `FrameClock` is designed to be compatible with an OpenGL-based implementation or with mozRequestAnimationFrame in Firefox, for example. A frame clock is idle until someone requests a frame with `FrameClock::request_phase`. At some later point that makes sense for the synchronization being implemented, the clock will process a frame and emit signals for each phase that has been requested. (See the signals of the `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`. 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 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` and the value inside the `FrameClock::update` signal of the clock, they will stay exactly synchronized. Starts updates for an animation. Until a matching call to `FrameClock::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 number of times. Stops updates for an animation. See the documentation for `FrameClock::begin_updating`. Gets the frame timings for the current frame. # Returns the `FrameTimings` for the frame currently being processed, or even no frame is being processed, for the previous frame. Before any frames have been processed, returns `None`. A `FrameClock` maintains a 64-bit counter that increments for each frame drawn. # Returns 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 the time of the conceptual “previous frame,” which may be either the actual previous frame time, or if that’s too old, an updated time. # Returns 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 is the set from the counter values given by `FrameClock::get_history_start` and `FrameClock::get_frame_counter`, inclusive. # Returns 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, predicts a presentation time that is a multiple of the refresh interval after the last presentation time, and later than `base_time`. ## `base_time` base time for determining a presentaton time ## `refresh_interval_return` a location to store the determined refresh interval, or `None`. A default refresh interval of 1/60th of a second will be stored if no history is present. ## `presentation_time_return` 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`. ## `frame_counter` the frame counter value identifying the frame to be received. # Returns the `FrameTimings` object for the specified frame, or `None` if it is not available. See `FrameClock::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 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 this allows GTK+ to adjust system parameters to get maximally smooth animations. ## `phase` the phase that is requested This signal ends processing of the frame. Applications should generally not handle this signal. This signal begins processing of the frame. Applications should generally not handle this signal. This signal is used to flush pending motion events that are being batched up and compressed together. Applications should not handle this signal. This signal is emitted as the second step of toolkit and application processing of the frame. Any work to update sizes and positions of application elements should be performed. GTK+ normally handles this internally. This signal is emitted as the third step of toolkit and application processing of the frame. The frame is repainted. GDK normally handles this internally and produces expose events, which are turned into GTK+ ``GtkWidget`::draw` signals. This signal is emitted after processing of the frame is finished, and is handled internally by GTK+ to resume normal event processing. Applications should not handle this signal. This signal is emitted as the first step of toolkit and application processing of the frame. Animations should be updated using `FrameClock::get_frame_time`. Applications can connect directly to this signal, or use `gtk_widget_add_tick_callback` as a more convenient interface. 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`. 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. The timing information in a `FrameTimings` is filled in incrementally as the frame as drawn and passed off to the window system for processing and display to the user. The accessor functions for `FrameTimings` can return 0 to indicate an unavailable value for two reasons: either because the information is not yet available, or because it isn't available at all. Once `FrameTimings::get_complete` returns `true` for a frame, you can be certain that no further values will become available and be stored in the `FrameTimings`. # Returns `true` if all information that will be available for the frame has been filled in. Gets the frame counter value of the `FrameClock` when this this frame was drawn. # Returns 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`. # Returns the frame time for the frame, in the timescale of `g_get_monotonic_time` Gets the predicted time at which this frame will be displayed. Although no predicted time may be available, if one is available, it will be available while the frame is being generated, in contrast to `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 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. # Returns The predicted time at which the frame will be presented, in the timescale of `g_get_monotonic_time`, or 0 if no predicted presentation time is available. Reurns the presentation time. This is the time at which the frame became visible to the user. # Returns the time the frame was displayed to the user, in the timescale of `g_get_monotonic_time`, or 0 if no presentation time is available. See `FrameTimings::get_complete` Gets the natural interval between presentation times for the display that this frame was displayed on. Frame presentation usually happens during the “vertical blanking interval”. # Returns the refresh interval of the display, in microseconds, or 0 if the refresh interval is not available. See `FrameTimings::get_complete`. Increases the reference count of `self`. # Returns `self` Decreases the reference count of `self`. If `self` is no longer referenced, it will be freed. Indicates which monitor (in a multi-head setup) a window should span over when in fullscreen mode. Fullscreen on current monitor only. Span across all monitors when fullscreen. `GLContext` is an object representing the platform-specific OpenGL drawing context. ``GdkGLContexts`` are created for a `Window` using `WindowExt::create_gl_context`, and the context will match the `Visual` of the window. A `GLContext` is not tied to any particular normal framebuffer. For instance, it cannot draw to the `Window` back buffer. The GDK repaint system is in full control of the painting to that. Instead, you can create render buffers or textures and use `gdk_cairo_draw_from_gl` in the draw function of your widget to draw them. Then GDK will handle the integration of your rendering with that of other widgets. Support for `GLContext` is platform-specific, context creation can fail, returning `None` context. A `GLContext` has to be made "current" in order to start using it, otherwise any OpenGL call will be ignored. ## Creating a new OpenGL context ## In order to create a new `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 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 `WindowExt::create_gl_context` by calling `GLContext::realize`. If the realization fails you have the option to change the settings of the `GLContext` and try again. ## Using a `GLContext` ## You will need to make the `GLContext` the current context before issuing OpenGL calls; the system sends OpenGL commands to whichever context is current. It is possible to have multiple contexts, so you always need to ensure that the one which you want to draw with is the current one before issuing commands: ```C gdk_gl_context_make_current (context); ``` You can now perform your drawing using OpenGL commands. You can check which `GLContext` is the current one by using `GLContext::get_current`; you can also unset any `GLContext` that is currently set by calling `GLContext::clear_current`. Feature: `v3_16` Clears the current `GLContext`. Any OpenGL call after this function returns will be ignored until `GLContext::make_current` is called. Feature: `v3_16` Retrieves the current `GLContext`. Feature: `v3_16` # Returns the current `GLContext`, or `None` Retrieves the value set using `GLContext::set_debug_enabled`. Feature: `v3_16` # Returns `true` if debugging is enabled Retrieves the `Display` the `self` is created for Feature: `v3_16` # Returns a `Display` or `None` Retrieves the value set using `GLContext::set_forward_compatible`. 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`. Feature: `v3_16` ## `major` 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` # 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. Feature: `v3_16` ## `major` return location for the major version ## `minor` return location for the minor version Retrieves the `Window` used by the `self`. 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`. 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. The `GLContext` must not be realized or made current prior to calling this function. 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 has been marked as deprecated in the requested version; non-forward compatible contexts, on the other hand, must support both deprecated and non deprecated functionality. The `GLContext` must not be realized or made current prior to calling this function. 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. The `GLContext` must not be realized or made current prior to calling this function. Feature: `v3_16` ## `major` 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 `GLContext::get_use_es` after calling `GLContext::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 The `Display` used to create the `GLContext`. Feature: `v3_16` The `Display` used to create the `GLContext`. Feature: `v3_16` The `GLContext` that this context is sharing data with, or `None` Feature: `v3_16` The `GLContext` that this context is sharing data with, or `None` Feature: `v3_16` The `Window` the gl context is bound to. Feature: `v3_16` The `Window` the gl context is bound to. Feature: `v3_16` Error enumeration for `GLContext`. OpenGL support is not available The requested visual format is not supported 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. All other devices’ events are allowed. Other devices’ events are blocked for the grab window. Other devices’ events are blocked for the whole application. Returned by `Device::grab`, `gdk_pointer_grab` and `gdk_keyboard_grab` to indicate success or the reason for the failure of the grab attempt. the resource was successfully grabbed. the resource is actively grabbed by another client. the resource was grabbed more recently than the specified time. the grab window or the `confine_to` window are not viewable. the resource is frozen by an active grab of another client. the grab failed for some other reason. Since 3.16 Defines the reference point of a window and the meaning of coordinates passed to `gtk_window_move`. See `gtk_window_move` and the "implementation notes" section of the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification for more details. the reference point is at the top left corner. the reference point is in the middle of the top edge. the reference point is at the top right corner. the reference point is at the middle of the left edge. the reference point is at the center of the window. the reference point is at the middle of the right edge. the reference point is at the lower left corner. the reference point is at the middle of the lower edge. the reference point is at the lower right corner. the reference point is at the top left corner of the window itself, ignoring window manager decorations. An enumeration that describes the mode of an input device. the device is disabled and will not report any events. the device is enabled. The device’s coordinate space maps to the entire screen. the device is enabled. The device’s coordinate space is mapped to a single window. The manner in which this window is chosen is undefined, but it will typically be the same way in which the focus window for key events is determined. An enumeration describing the type of an input device in general terms. the device is a mouse. (This will be reported for the core pointer, even if it is something else, such as a trackball.) the device is a stylus of a graphics tablet or similar device. the device is an eraser. Typically, this would be the other end of a stylus on a graphics tablet. the device is a graphics tablet “puck” or similar device. the device is a keyboard. the device is a direct-input touch device, such as a touchscreen or tablet. This device type has been added in 3.4. the device is an indirect touch device, such as a touchpad. This device type has been added in 3.4. the device is a trackpoint. This device type has been added in 3.22 the device is a "pad", a collection of buttons, rings and strips found in drawing tablets. This device type has been added in 3.22. This enum is used with `Keymap::get_modifier_mask` in order to determine what modifiers the currently used windowing system backend uses for particular purposes. For example, on X11/Windows, the Control key is used for invoking menu shortcuts (accelerators), whereas on Apple computers it’s the Command key (which correspond to `ModifierType::ControlMask` and `ModifierType::Mod2Mask`, respectively). the primary modifier used to invoke menu accelerators. the modifier used to invoke context menus. Note that mouse button 3 always triggers context menus. When this modifier is not 0, it additionally triggers context menus when used with mouse button 1. the modifier used to extend selections using `modifier`-click or `modifier`-cursor-key the modifier used to modify selections, which in most cases means toggling the clicked item into or out of the selection. when any of these modifiers is pressed, the key event cannot produce a symbol directly. This is meant to be used for input methods, and for use cases like typeahead search. the modifier that switches between keyboard groups (AltGr on X11/Windows and Option/Alt on OS X). The set of modifier masks accepted as modifiers in accelerators. Needed because Command is mapped to MOD2 on OSX, which is widely used, but on X11 MOD2 is NumLock and using that for a mod key is problematic at best. Ref: https://bugzilla.gnome.org/show_bug.cgi?id=736125. `Monitor` objects represent the individual outputs that are associated with a `Display`. `Display` has APIs to enumerate monitors with `Display::get_n_monitors` and `Display::get_monitor`, and to find particular monitors with `Display::get_primary_monitor` or `Display::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` 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 `Monitor::get_scale_factor`). Feature: `v3_22` ## `geometry` a `Rectangle` to be filled with 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. Feature: `v3_22` # Returns the name of the manufacturer, or `None` Gets the a string identifying the monitor model, if available. Feature: `v3_22` # 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 `Monitor::get_scale_factor`). The work area should be considered when positioning menus and similar popups, to avoid placing them below panels, docks or other desktop components. Note that not all backends may have a concept of workarea. This function will return the monitor geometry if a workarea is not available, or does not apply. Feature: `v3_22` ## `workarea` a `Rectangle` to be filled with the monitor workarea Gets whether this monitor should be considered primary (see `Display::get_primary_monitor`). Feature: `v3_22` # Returns `true` if `self` is primary Specifies the kind of crossing for `EventCrossing`. See the X11 protocol specification of LeaveNotify for full details of crossing event generation. the window is entered from an ancestor or left towards an ancestor. the pointer moves between an ancestor and an inferior of the window. the window is entered from an inferior or left towards an inferior. the window is entered from or left towards a window which is neither an ancestor nor an inferior. the pointer moves between two windows which are not ancestors of each other and the window is part of the ancestor chain between one of these windows and their least common ancestor. an unknown type of enter/leave event occurred. Specifies why a selection ownership was changed. some other app claimed the ownership the window was destroyed the client was closed 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 cairo’s 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 percentage 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`). `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. Gets the default screen for the default display. (See gdk_display_get_default ()). # Returns a `Screen`, or `None` if there is no default display. Gets the height of the default screen in pixels. The returned size is in ”application pixels”, not in ”device pixels” (see `Screen::get_monitor_scale_factor`). # Deprecated since 3.22 Use per-monitor information # Returns 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. Gets the width of the default screen in pixels. The returned size is in ”application pixels”, not in ”device pixels” (see `Screen::get_monitor_scale_factor`). # Deprecated since 3.22 Use per-monitor information # Returns 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 on the root window, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec). If there is no currently currently active window, or the window manager does not support the _NET_ACTIVE_WINDOW hint, this function returns `None`. On other platforms, this function may return `None`, depending on whether 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`. # Returns the current font options, or `None` if no default font options have been set. Gets the height of `self` in pixels. The returned size is in ”application pixels”, not in ”device pixels” (see `Screen::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 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 `Display::get_monitor_at_point` instead ## `x` the x coordinate in the virtual screen. ## `y` the y coordinate in the virtual screen. # Returns 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 `Display::get_monitor_at_window` instead ## `window` a `Window` # Returns 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 returned geometry is in ”application pixels”, not in ”device pixels” (see `Screen::get_monitor_scale_factor`). Monitor numbers start at 0. To obtain the number of monitors of `self`, use `Screen::get_n_monitors`. Note that the size of the entire screen area can be retrieved via `Screen::get_width` and `Screen::get_height`. # Deprecated since 3.22 Use `Monitor::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 `Monitor::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 `Monitor::get_model` instead ## `monitor_num` number of the monitor, between 0 and gdk_screen_get_n_monitors (screen) # Returns 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 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. # Deprecated since 3.22 Use `Monitor::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 `Monitor::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 returned geometry is in ”application pixels”, not in ”device pixels” (see `Screen::get_monitor_scale_factor`). The work area should be considered when positioning menus and similar popups, to avoid placing them below panels, docks or other desktop components. Note that not all backends may have a concept of workarea. This function will return the monitor geometry if a workarea is not available, or does not apply. Monitor numbers start at 0. To obtain the number of monitors of `self`, use `Screen::get_n_monitors`. # Deprecated since 3.22 Use `Monitor::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 `Display::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`) # 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 manager to place the windows, specialized desktop applications such as panels should place themselves on the primary monitor. If no primary monitor is configured by the user, the return value will be 0, defaulting to the first monitor. # Deprecated since 3.22 Use `Display::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. # 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 be returned. Even if a non-`None` value is returned, its possible that the window’s alpha channel won’t be honored when displaying the window on the screen: in particular, for X an appropriate windowing manager and compositing manager must be running to provide appropriate display. This functionality is not implemented in the Windows backend. For setting an overall opacity for a top-level window, see `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`. FIXME needs a list of valid settings here, or a link to more information. ## `name` the name of the setting ## `value` location to store the value of the setting # Returns `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. # 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`). The returned list should be freed with `glib::List::free`, but its elements need not be freed. # Returns list of toplevel windows, free with `glib::List::free` Gets the width of `self` in pixels. The returned size is in ”application pixels”, not in ”device pixels” (see `Screen::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 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. On X11, this is done by inspecting the _NET_CLIENT_LIST_STACKING property on the root window, as described in the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec). If the window manager does not support the _NET_CLIENT_LIST_STACKING hint, this function returns `None`. On other platforms, this function may return `None`, depending on whether it is implementable on that platform. The returned list is newly allocated and owns references to the windows it contains, so it should be freed using `glib::List::free` and its windows unrefed using `gobject::Object::unref` when no longer needed. # Returns 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. On X11 this function returns whether a compositing manager is compositing `self`. # Returns 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, and might expect pixels to be in a certain format. Call `glib::List::free` on the return value when you’re finished with it. # Returns 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 default set of font options does not affect contexts that 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 font will be 13 units high. (10 * 96. / 72. = 13.3). ## `dpi` the resolution in “dots per inch”. (Physical inches aren’t actually involved; the terminology is conventional.) The ::composited-changed signal is emitted when the composited status of the screen changes The ::monitors-changed signal is emitted when the number, size or position of the monitors attached to the screen change. Only for X11 and OS X for now. A future implementation for Win32 may be a possibility. The ::size-changed signal is emitted when the pixel width or height of a screen changes. Specifies the direction for `EventScroll`. the window is scrolled up. the window is scrolled down. the window is scrolled to the left. the window is scrolled to the right. the scrolling is determined by the delta values in `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` Returns the capabilities this `Seat` currently has. Feature: `v3_20` # Returns the seat capabilities Returns the `Display` this seat belongs to. Feature: `v3_20` # 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 `Seat::ungrab`, or the window becomes hidden. This overrides any previous grab on the seat by this client. As a rule of thumb, if a grab is desired over `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 `Seat::grab`. Feature: `v3_20` The ::device-added signal is emitted when a new input device is related to this seat. Feature: `v3_20` ## `device` the newly added `Device`. The ::device-removed signal is emitted when an input device is removed (e.g. unplugged). Feature: `v3_20` ## `device` the just removed `Device`. The ::tool-added signal is emitted whenever a new tool is made known to the seat. The tool may later be assigned to a device (i.e. on proximity with a tablet). The device will emit the `Device::tool-changed` signal accordingly. A same tool may be used by several devices. Feature: `v3_22` ## `tool` the new `DeviceTool` known to the seat This signal is emitted whenever a tool is no longer known to this `seat`. Feature: `v3_22` ## `tool` the just removed `DeviceTool` `Display` of this seat. Feature: `v3_20` `Display` of this seat. Feature: `v3_20` Specifies the kind of modification applied to a setting in a `EventSetting`. 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`. the window is completely visible. the window is partially visible. the window is not visible at all. A `Visual` contains information about a particular visual. Get the visual with the most available colors for the default GDK screen. The return value should not be freed. # Deprecated since 3.22 Visual selection should be done using `Screen::get_system_visual` and `Screen::get_rgba_visual` # Returns best visual Get the best available depth for the default GDK screen. “Best” means “largest,” i.e. 32 preferred over 24 preferred over 8 bits per pixel. # Deprecated since 3.22 Visual selection should be done using `Screen::get_system_visual` and `Screen::get_rgba_visual` # Returns best available depth Return the best available visual type for the default GDK screen. # Deprecated since 3.22 Visual selection should be done using `Screen::get_system_visual` and `Screen::get_rgba_visual` # Returns best visual type Combines `Visual::get_best_with_depth` and `Visual::get_best_with_type`. # Deprecated since 3.22 Visual selection should be done using `Screen::get_system_visual` and `Screen::get_rgba_visual` ## `depth` a bit depth ## `visual_type` a visual type # Returns best visual with both `depth` and `visual_type`, or `None` if none Get the best visual with depth `depth` for the default GDK screen. Color visuals and visuals with mutable colormaps are preferred over grayscale or fixed-colormap visuals. The return value should not be freed. `None` may be returned if no visual supports `depth`. # Deprecated since 3.22 Visual selection should be done using `Screen::get_system_visual` and `Screen::get_rgba_visual` ## `depth` a bit depth # Returns best visual for the given depth Get the best visual of the given `visual_type` for the default GDK screen. Visuals with higher color depths are considered better. The return value should not be freed. `None` may be returned if no visual has type `visual_type`. # Deprecated since 3.22 Visual selection should be done using `Screen::get_system_visual` and `Screen::get_rgba_visual` ## `visual_type` a visual type # Returns best visual of the given type Get the system’s default visual for the default GDK screen. This is the visual for the root window of the display. The return value should not be freed. # Deprecated since 3.22 Use gdk_screen_get_system_visual (gdk_screen_get_default ()). # 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 `Visual::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 to be in position (according to the "mask"). Finally, "precision" refers to how much precision the pixel value contains for a particular primary. ## `mask` A pointer to a `guint32` to be filled in, or `None` ## `shift` 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 to be in position (according to the "mask"). Finally, "precision" refers to how much precision the pixel value contains for a particular primary. ## `mask` A pointer to a `guint32` to be filled in, or `None` ## `shift` 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 to be in position (according to the "mask"). Finally, "precision" refers to how much precision the pixel value contains for a particular primary. ## `mask` A pointer to a `guint32` to be filled in, or `None` ## `shift` 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 A `VisualType` stating the type of `self`. A set of values that describe the manner in which the pixel values for a visual are converted into RGB values for display. Each pixel value indexes a grayscale value directly. Each pixel is an index into a color map that maps pixel values into grayscale values. The color map can be changed by an application. Each pixel value is an index into a predefined, unmodifiable color map that maps pixel values into RGB values. Each pixel is an index into a color map that maps pixel values into rgb values. The color map can be changed by an application. Each pixel value directly contains red, green, and blue components. Use `Visual::get_red_pixel_details`, etc, to obtain information about how the components are assembled into a pixel value. Each pixel value contains red, green, and blue components as for `VisualType::TrueColor`, but the components are mapped via a color table into the final output table instead of being converted directly. # Implements [`WindowExt`](trait.WindowExt.html), [`WindowExtManual`](prelude/trait.WindowExtManual.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 more details. Note: to use this on displays other than the default display, `parent` must be specified. ## `parent` a `Window`, or `None` to create the window as a child of the default root window for the default display. ## `attributes` attributes of the new window ## `attributes_mask` mask indicating which fields in `attributes` are valid # Returns the new `Window` Constrains a desired width and height according to a set of geometry hints (such as minimum and maximum size). ## `geometry` a `Geometry` structure ## `flags` a mask indicating what portions of `geometry` are set ## `width` desired width of window ## `height` desired height of the window ## `new_width` location to store resulting width ## `new_height` location to store resulting height Calls `WindowExt::process_updates` for all windows (see `Window`) in the application. # Deprecated since 3.22 With update debugging enabled, calls to `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 `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. In essence, because the GDK rendering model prevents all flicker, if you are redrawing the same region 400 times you may never notice, aside from noticing a speed problem. Enabling update debugging causes GTK to flicker slowly and noticeably, so you can see exactly what’s being redrawn when, in what order. The --gtk-debug=updates command line option passed to GTK+ programs enables this debug option at application startup time. That's usually more useful than calling `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 doing. Pass `None` for `self` to get all events for all windows, instead of events for a specific window. If you are interested in X GenericEvents, bear in mind that XGetEventData() has been already called on the event, and XFreeEventData() must not be called within `function`. ## `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`. 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 `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 ## `root_x` root window X coordinate of mouse click that began the drag ## `root_y` 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 [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) but has a fallback implementation for other window managers. ## `device` the device used for the operation ## `button` the button being used to drag, or 0 for a keyboard-initiated drag ## `root_x` root window X coordinate of mouse click that began the drag ## `root_y` root window Y coordinate of mouse click that began the drag ## `timestamp` timestamp of mouse click that began the drag A convenience wrapper around `WindowExt::begin_paint_region` which creates a rectangular region for you. See `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 `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 `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 `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 `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 `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 `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 `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 `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 ## `button` the button being used to drag, or 0 for a keyboard-initiated drag ## `root_x` root window X coordinate of mouse click that began the drag ## `root_y` 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 with window managers that support the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) but has a fallback implementation for other window managers. ## `edge` the edge or corner from which the drag is started ## `device` the device used for the operation ## `button` the button being used to drag, or 0 for a keyboard-initiated drag ## `root_x` root window X coordinate of mouse click that began the drag ## `root_y` 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`) Transforms window coordinates from a parent window to a child window, where the parent window is the normal parent as returned by `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 `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. You should always use this function when writing generic code that walks down a window hierarchy. See also: `WindowExt::coords_to_parent` ## `parent_x` X coordinate in parent’s coordinate system ## `parent_y` Y coordinate in parent’s coordinate system ## `x` 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 `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 `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. You should always use this function when writing generic code that walks up a window hierarchy. See also: `WindowExt::coords_from_parent` ## `x` X coordinate in child’s coordinate system ## `y` Y coordinate in child’s coordinate system ## `parent_x` return location for X coordinate 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. 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`. Feature: `v3_16` # Returns 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); ``` Note that unlike `cairo_surface_create_similar_image`, the new surface's device scale is set to `scale`, or to the scale factor of `self` if `scale` is 0. ## `format` the format for the new surface ## `width` width of the new surface ## `height` height of the new surface ## `scale` the scale of the new surface, or 0 to use same as `self` # Returns a pointer to the newly allocated surface. The caller owns the surface and should call `cairo_surface_destroy` when done with it. This function always returns a valid pointer, but it will return a pointer to a “nil” surface if `other` is already in an error state or any other error occurs. 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 surface will also use the same backend as `self`, unless that is not possible for some reason. The type of the returned surface may be examined with `cairo_surface_get_type`. Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.) ## `content` the content for the new surface ## `width` width of the new surface ## `height` height of the new surface # Returns a pointer to the newly allocated surface. The caller owns the surface and should call `cairo_surface_destroy` when done with it. This function always returns a valid pointer, but it will return a pointer to a “nil” surface if `other` is already in an error state or any other error occurs. 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. 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 `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 `WindowExt::begin_paint_region` for full details. It is an error to call this function without a matching `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`. Offscreen window and children of them can never have native windows. Some backends may not support native child windows. # Returns `true` if the window has a native window, `false` otherwise 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 `WindowExt::thaw_toplevel_updates_libgtk_only` is called. If `WindowExt::freeze_toplevel_updates_libgtk_only` has been called more than once, `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 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 `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. If the window was already fullscreen, then this function does nothing. On X11, asks the window manager to put `self` in a fullscreen state, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “fullscreen”; so you can’t rely on the fullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. 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`. # Deprecated since 3.22 Don't use this function # Returns The pattern to use for the background or `None` if there is no 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; it only returns windows an application created itself. The returned list must be freed, but the elements in the list need not be. # Returns list of child windows inside `self` Gets the list of children of `self` known to GDK with a particular `user_data` set on it. The returned list must be freed, but the elements in the list need not be. The list is returned in (relative) stacking order, i.e. the lowest window is first. ## `user_data` user data to look for # Returns 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, but no area outside of this region will be affected by drawing primitives. # Returns a `cairo::Region`. This must be freed with `cairo_region_destroy` when you are done. Determines whether `self` is composited. See `WindowExt::set_composited`. # Deprecated since 3.16 Compositing is an outdated technology that only ever worked on X11. # 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 using the cursor for its parent window. # Returns a `Cursor`, or `None`. The returned object is owned by the `Window` and should not be unreferenced directly. Use `WindowExt::set_cursor` to unset the cursor of the window Returns the decorations set on the `Window` with `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 using the cursor for its parent window. ## `device` a master, pointer `Device`. # Returns a `Cursor`, or `None`. The returned object is owned by the `Window` and should not be 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`. # 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 `WindowExt::get_device_position_double` if you need subpixel precision. ## `device` pointer `Device` to query to. ## `x` return location for the X coordinate of `device`, or `None`. ## `y` return location for the Y coordinate of `device`, or `None`. ## `mask` return location for the modifier mask, or `None`. # Returns The window underneath `device` (as with `Device::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`. ## `device` pointer `Device` to query to. ## `x` return location for the X coordinate of `device`, or `None`. ## `y` return location for the Y coordinate of `device`, or `None`. ## `mask` return location for the modifier mask, or `None`. # Returns The window underneath `device` (as with `Device::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 where the drop should happen. This may be `self` or a proxy window, or `None` if `self` does not support Drag and Drop. # Returns the supported DND protocol. Obtains the parent of `self`, as known to GDK. Works like `WindowExt::get_parent` for normal windows, but returns the window’s embedder for offscreen windows. See also: `gdk_offscreen_window_get_embedder` # Returns effective parent of `self` Gets the toplevel window that’s an ancestor of `self`. 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. # Returns `true` if motion events will be compressed Gets the event mask for `self` for all master input devices. See `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. # Returns 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. # 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 `WindowExt::get_origin`. ## `rect` rectangle to fill with bounding box of the window frame Obtains the `FullscreenMode` of the `self`. # 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. The X and Y coordinates returned are relative to the parent window of `self`, which for toplevels usually means relative to the window decorations (titlebar, etc.) rather than relative to the root window (screen-size background window). On the X11 platform, the geometry is obtained from the X server, so reflects the latest position of `self`; this may be out-of-sync with the position of `self` delivered in the most-recently-processed `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 `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 `WindowExt::get_geometry` is restricted to the 16-bit coordinates of X11. ## `x` return location for X coordinate of window (relative to its parent) ## `y` return location for Y coordinate of window (relative to its parent) ## `width` return location for width of window ## `height` return location for height of window 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 most-recently-processed configure event, rather than the current 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 `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 ## `y` 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 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 `WindowExt::get_effective_parent` when writing generic code that walks up a window hierarchy, because `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 position of the window as reported in the most-recently-processed `EventConfigure`. Contrast with `WindowExt::get_geometry` which queries the X server for the current window position, regardless of which events have been received or processed. The position coordinates are relative to the window’s parent window. ## `x` X coordinate of window ## `y` Y coordinate of window Obtains the position of a window position in root window coordinates. This is similar to `WindowExt::get_origin` but allows you to pass in any position in the window, not just the origin. ## `x` X coordinate in window ## `y` Y coordinate in window ## `root_x` 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). A higher value means that drawing is automatically scaled up to a higher resolution, so any code doing drawing will automatically look nicer. However, if you are supplying pixel-based data the scale value can be used to determine whether to use a pixel resource with higher resolution data. The scale of a window may change during runtime, if this happens a configure event will be sent to the toplevel window. # 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` 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 `WindowExt::get_effective_toplevel` when you want to get to a window’s toplevel as seen on screen, because `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, `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`. ## `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 is visible. # Returns 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 most-recently-processed configure event, rather than the current 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 `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 `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`. An input shape is typically used with RGBA windows. The alpha channel of the window defines which pixels are invisible and allows for nicely antialiased borders, and the input shape controls where the window is “clickable”. On the X11 platform, this requires version 1.1 of the shape extension. On the Win32 platform, this functionality is not present and the function does nothing. ## `shape_region` region of window to be non-transparent ## `offset_x` 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 `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. GDK will call `Window::process_all_updates` on your behalf whenever your program returns to the main loop and becomes idle, so normally there’s no need to do that manually, you just need to invalidate regions that you know should be redrawn. The `child_func` parameter controls whether the region of each child window that intersects `region` will also be invalidated. Only children for which `child_func` returns `true` will have the area invalidated. ## `region` a `cairo::Region` ## `child_func` 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 `WindowExt::invalidate_region` which invalidates a rectangular region. See `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 `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. GDK will call `Window::process_all_updates` on your behalf whenever your program returns to the main loop and becomes idle, so normally there’s no need to do that manually, you just need to invalidate regions that you know should be redrawn. The `invalidate_children` parameter controls whether the region of each child window that intersects `region` will also be invalidated. If `false`, then the update area for child windows will remain unaffected. See gdk_window_invalidate_maybe_recurse if you need fine grained control over which children are invalidated. ## `region` 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 window.) # Returns `true` if the window is viewable 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, `WindowExt::lower` only requests the restack, does not guarantee it. 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. This is typically called automatically by GTK+ and you don't need to care about this. Feature: `v3_16` ## `cr` a `cairo::Context` Maximizes the window. If the window was already maximized, then this function does nothing. On X11, asks the window manager to maximize `self`, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “maximized”; so you can’t rely on the maximization actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. On Windows, reliably maximizes the window. 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 `WindowExt::input_shape_combine_region`. 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 `WindowExt::shape_combine_region`. 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 `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. Child windows are not moved. ## `region` The `cairo::Region` to move ## `dx` Amount to move in the X direction ## `dy` Amount to move in the Y direction 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 `WindowExt::move_resize`.) ## `x` new X position relative to window’s parent ## `y` new Y position relative to window’s parent ## `width` new width ## `height` new height Moves `self` to `rect`, aligning their anchor points. `rect` is relative to the top-left corner of the window that `self` is transient for. `rect_anchor` and `window_anchor` determine anchor points on `rect` and `self` to pin together. `rect`'s anchor point can optionally be offset by `rect_anchor_dx` and `rect_anchor_dy`, which is equivalent to offsetting the position of `self`. `anchor_hints` determines how `self` will be moved if the anchor points cause it to move off-screen. For example, `AnchorHints::FlipX` will replace `Gravity::NorthWest` with `Gravity::NorthEast` and vice versa if `self` extends beyond the left or right edges of the monitor. Connect to the `Window::moved-to-rect` signal to find out how it was actually positioned. Feature: `v3_24` ## `rect` the destination `Rectangle` to align `self` with ## `rect_anchor` the point on `rect` to align with `self`'s anchor point ## `window_anchor` the point on `self` to align with `rect`'s anchor point ## `anchor_hints` positioning hints to use when limited on space ## `rect_anchor_dx` horizontal offset to shift `self`, i.e. `rect`'s anchor point ## `rect_anchor_dy` vertical offset to shift `self`, i.e. `rect`'s anchor point 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 `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 case, where GDK delivers them in an idle handler). Occasionally this is useful to produce nicer scrolling behavior, for example. # Deprecated since 3.22 ## `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, `WindowExt::raise` only requests the restack, does not guarantee it. Registers a window as a potential drop destination. 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` new parent to move `self` into ## `x` 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 `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`). 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, `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 invalidated. The invalidated region may be bigger than what would strictly be necessary. For X11, a minimum area will be invalidated if the window has no subwindows, or if the edges of the window’s parent do not extend beyond the edges of the window. In other cases, a multi-step process is used to scroll the window which may produce temporary visual artifacts and unnecessary invalidations. ## `dx` 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. 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 of `self`. A background of `None` means that the window won't have any background. On the X11 backend it's also possible to inherit the background from the parent window using `gdk_x11_get_parent_relative_pattern`. The windowing system will normally fill a window with its background when the window is obscured then exposed. # 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`. # 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 `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 `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 and an expose event is emitted on the parent of the composited window. It is the responsibility of the parent’s expose handler to manually merge the off-screen content onto the screen in whatever way it sees fit. It only makes sense for child windows to be composited; see `WindowExt::set_opacity` if you need translucent toplevel windows. An additional effect of this call is that the area of this window is no longer clipped from regions marked for invalidation on its parent. Draws done on the parent window are also no longer clipped by the child. This call is only supported on some systems (currently, only X11 with new enough Xcomposite and Xdamage extensions). You must call `Display::supports_composite` to check if setting a window as composited is supported before attempting to do so. # Deprecated since 3.16 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 `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. Usually you should use `gtk_window_set_decorated` on a ``GtkWindow`` instead of using the GDK function directly. The `decorations` argument is the logical OR of the fields in the `WMDecoration` enumeration. If `WMDecoration::All` is included in the mask, the other bits indicate which decorations should be turned off. If `WMDecoration::All` is not included, then the other bits indicate which decorations should be turned on. Most window managers honor a decorations hint of 0 to disable all decorations, but very few honor all possible combinations of bits. ## `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 `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 press events. The event mask is the bitwise OR of values from the `EventMask` enumeration. See the [input handling overview][event-masks] for details. ## `device` `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. Some types of applications, e.g. paint programs, need to see all motion events and will benefit from turning off event compression. By default, event compression is enabled. ## `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 press events. The event mask is the bitwise OR of values from the `EventMask` enumeration. 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 interactively (such as popups from network activity). On X, it is the responsibility of the window manager to interpret this hint. Window managers following the freedesktop.org window manager extension specification should respect it. ## `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. The `mode` argument is from the `FullscreenMode` enumeration. If `FullscreenMode::AllMonitors` is specified, the fullscreen `self` will span over all monitors from the `Screen`. On X11, searches through the list of monitors from the `Screen` the ones which delimit the 4 edges of the entire `Screen` and will ask the window manager to span the `self` over these monitors. If the XINERAMA extension is not available or not usable, this function has no effect. Not all window managers support this, so you can’t rely on the fullscreen window to span over the multiple monitors when `FullscreenMode::AllMonitors` is specified. ## `mode` fullscreen mode Sets hints about the window management functions to make available via buttons on the window frame. On the X backend, this function sets the traditional Motif window manager hint for this purpose. However, few window managers do anything reliable or interesting with this hint. Many ignore it entirely. The `functions` argument is the logical OR of values from the `WMFunction` enumeration. If the bitmask includes `WMFunction::All`, then the other bits indicate which functions to disable; if 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`. This function provides hints to the windowing system about acceptable sizes for a toplevel window. The purpose of this is to constrain user resizing, but the windowing system will typically (but is not required to) also constrain the current size of the window to the provided values and constrain programatic resizing via `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 `WindowExt::set_override_redirect` since these windows are not resizable by the user. Since you can’t count on the windowing system doing the constraints for programmatic resizes, you should generally call `Window::constrain_size` yourself to determine appropriate sizes. ## `geometry` 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 you can override this default. The group leader window allows the window manager to distinguish all windows that belong to a single application. It may for example allow users to minimize/unminimize all windows belonging to an application at once. You should only set a non-default group window if your application pretends to be multiple applications. ## `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 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 `WindowExt::set_title` will not update the icon title. Using `None` for `name` unsets the icon title; further calls to `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. This can be used to record the invalidated region, which is useful if you are keeping an offscreen copy of some region and want to keep it up to date. You can also modify the invalidated region in case you’re doing some effect where e.g. a child widget appears in multiple places. ## `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. On X11, asks the window manager to keep `self` above, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “keep above”; so you can’t rely on the window being kept above. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. ## `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. On X11, asks the window manager to keep `self` below, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “keep below”; so you can’t rely on the window being kept below. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. ## `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 `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.) For toplevel windows this depends on support from the windowing system that may not always be there. For instance, On X11, this works only on X screens with a compositing manager running. On Wayland, there is no per-window opacity value that the compositor would apply. Instead, use `gdk_window_set_opaque_region (window, NULL)` to tell the compositor that the entire window is (potentially) non-opaque, and draw your content with alpha, or use `gtk_widget_set_opacity` to set an overall opacity for your widgets. For child windows this function only works for non-native windows. For setting up per-pixel alpha topelevels, see `Screen::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, this is just the shape of the window, but with ARGB32 windows, the compositor does not know what regions of the window are transparent or not. This function only works for toplevel windows. GTK+ will update this property automatically if the `self` background is opaque, as we know where the opaque regions are. If your window background is not opaque, please update this property in your ``GtkWidget`::style-updated` handler. ## `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 can’t see the override redirect window at all. Override redirect should only be used for short-lived temporary windows, such as popup menus. ``GtkMenu`` uses an override redirect window in its implementation, for example. ## `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. The window manager and session manager use a window’s role to distinguish it from other kinds of window in the same application. When an application is restarted after being saved in a previous session, all windows with the same title and role are treated as interchangeable. So if you have two windows with the same title that should be distinguished for session management purposes, you should set the role on those windows. It doesn’t matter what string you use for the role, as long as you have a different role for each non-interchangeable kind of window. ## `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 to know where the extents of the actual frame lie, so that users don’t feel like windows are snapping against random invisible edges. Note that this property is automatically updated by GTK+, so this function should only be used by applications which do not use GTK+ to create toplevel windows. ## `left` The left extent ## `right` The right extent ## `top` 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 `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 `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 after this call, and devices being attached/detached. ## `source` 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 windowing system. Don’t worry about it. # Deprecated since 3.16 static gravities haven't worked on anything but X11 for a long time. ## `use_static` `true` to turn on static gravity # 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 `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 keep `self` above `parent`. 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 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 `Window`. So, custom widget implementations should use this function for that. If GTK+ receives an event for a `Window`, 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. If `shape_region` is `None`, the shape will be unset, so the whole window will be opaque again. `offset_x` and `offset_y` are ignored if `shape_region` is `None`. On the X11 platform, this uses an X server extension which is widely available on most common platforms, but not available on very old X servers, and occasionally the implementation will be buggy. On servers without the shape extension, this function will do nothing. This function works on both toplevel and child windows. ## `shape_region` region of window to be non-transparent ## `offset_x` X position of `shape_region` in `self` coordinates ## `offset_y` Y position of `shape_region` in `self` coordinates 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 `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, `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 using client-side decorations, activating it with a right-click on the window decorations. ## `event` 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.) On the X11 platform, this function depends on window manager support, so may have no effect with many window managers. However, GDK will do the best it can to convince the window manager to stick the window. For window managers that don’t support this operation, there’s nothing you can do to force it to happen. Thaws a window frozen with `WindowExt::freeze_toplevel_updates_libgtk_only`. This function is not part of the GDK public API and is only for use by GTK+. # Deprecated since 3.16 This symbol was never meant to be used outside of GTK+ Thaws a window frozen with `WindowExt::freeze_updates`. Moves the window out of fullscreen mode. If the window was not fullscreen, does nothing. On X11, asks the window manager to move `self` out of the fullscreen state, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “fullscreen”; so you can’t rely on the unfullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. Unmaximizes the window. If the window wasn’t maximized, then this function does nothing. On X11, asks the window manager to unmaximize `self`, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don’t have a concept of “maximized”; so you can’t rely on the unmaximization actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen. On Windows, reliably unmaximizes the window. 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 `WindowExt::hide` automatically withdraws toplevel windows before hiding them. The ::create-surface signal is emitted when an offscreen window needs its surface (re)created, which happens either when the window is first drawn to, or when the window is being resized. The first signal handler that returns a non-`None` surface will stop any further signal emission, and its surface will be used. Note that it is not possible to access the window's previous surface from within any callback of this signal. Calling `gdk_offscreen_window_get_surface` will lead to a crash. ## `width` the width of the offscreen surface to create ## `height` the height of the offscreen surface to create # Returns the newly created `cairo::Surface` for the offscreen window The ::from-embedder signal is emitted to translate coordinates in the embedder of an offscreen window to the offscreen window. See also `Window::to-embedder`. ## `embedder_x` x coordinate in the embedder window ## `embedder_y` y coordinate in the embedder window ## `offscreen_x` return location for the x coordinate in the offscreen window ## `offscreen_y` return location for the y coordinate in the offscreen window Emitted when the position of `window` is finalized after being moved to a destination rectangle. `window` might be flipped over the destination rectangle in order to keep it on-screen, in which case `flipped_x` and `flipped_y` will be set to `true` accordingly. `flipped_rect` is the ideal position of `window` after any possible flipping, but before any possible sliding. `final_rect` is `flipped_rect`, but possibly translated in the case that flipping is still ineffective in keeping `window` on-screen. Feature: `v3_22` ## `flipped_rect` the position of `window` after any possible flipping or `None` if the backend can't obtain it ## `final_rect` the final position of `window` or `None` if the backend can't obtain it ## `flipped_x` `true` if the anchors were flipped horizontally ## `flipped_y` `true` if the anchors were flipped vertically The ::pick-embedded-child signal is emitted to find an embedded child at the given position. ## `x` x coordinate in the window ## `y` y coordinate in the window # Returns the `Window` of the embedded child at `x`, `y`, or `None` The ::to-embedder signal is emitted to translate coordinates in an offscreen window to its embedder. See also `Window::from-embedder`. ## `offscreen_x` x coordinate in the offscreen window ## `offscreen_y` y coordinate in the offscreen window ## `embedder_x` return location for the x coordinate in the embedder window ## `embedder_y` return location for the y coordinate in the embedder window The mouse pointer for a `Window`. See `WindowExt::set_cursor` and `WindowExt::get_cursor` for details. The mouse pointer for a `Window`. See `WindowExt::set_cursor` and `WindowExt::get_cursor` for details. Determines a window edge or corner. the top left corner. the top edge. the top right corner. the left edge. the right edge. the lower left corner. the lower edge. the lower right corner. Describes the kind of window. root window; this window has no parent, covers the entire screen, and is created by the window system toplevel window (used to implement ``GtkWindow``) child window (used to implement e.g. ``GtkEntry``) override redirect temporary window (used to implement ``GtkMenu``) foreign window (see `gdk_window_foreign_new`) offscreen window (see [Offscreen Windows][OFFSCREEN-WINDOWS]). Since 2.18 subsurface-based window; This window is visually tied to a toplevel, and is moved/stacked with it. Currently this window type is only implemented in Wayland. Since 3.14 These are hints for the window manager that indicate what type of function the window has. The window manager can use this when determining decoration and behaviour of the window. The hint must be set before mapping the window. See the [Extended Window Manager Hints](http://www.freedesktop.org/Standards/wm-spec) specification for more details about window types. Normal toplevel window. Dialog window. Window used to implement a menu; GTK+ uses this hint only for torn-off menus, see ``GtkTearoffMenuItem``. Window used to implement toolbars. Window used to display a splash screen during application startup. Utility windows which are not detached toolbars or dialogs. Used for creating dock or panel windows. Used for creating the desktop background window. A menu that belongs to a menubar. A menu that does not belong to a menubar, e.g. a context menu. A tooltip. A notification - typically a “bubble” that belongs to a status icon. A popup from a combo box. A window that is used to implement a DND cursor. `WindowWindowClass::InputOutput` windows are the standard kind of window you might expect. Such windows receive events and are also displayed on screen. `WindowWindowClass::InputOnly` windows are invisible; they are usually placed above other windows in order to trap or filter the events. You can’t draw on `WindowWindowClass::InputOnly` windows. window for graphics and events window for events only gtk-rs-lgpl-docs-0.1.12/gio/docs.md010064400007650000024000000011061344544746500151510ustar0000000000000000 This is stub for doc generation [Actual docs](https://doc.rust-lang.org/std/os/unix/io/trait.IntoRawFd.html) This is stub for doc generation [Actual docs](https://doc.rust-lang.org/std/os/unix/io/trait.FromRawFd.html) This is stub for doc generation [Actual docs](https://doc.rust-lang.org/std/os/windows/io/trait.IntoRawSocket.html) This is stub for doc generation [Actual docs](https://doc.rust-lang.org/std/os/windows/io/trait.FromRawSocket.html) gtk-rs-lgpl-docs-0.1.12/gio/vendor.md010064400007650000024000027736141350423663000155260ustar0000000000000000 `Action` represents a single named action. The main interface to an action is that it can be activated with `Action::activate`. This results in the 'activate' signal being emitted. An activation has a `glib::Variant` parameter (which may be `None`). The correct type for the parameter is determined by a static parameter type (which is given at construction time). An action may optionally have a state, in which case the state may be set with `Action::change_state`. This call takes a `glib::Variant`. The correct type for the state is determined by a static state type (which is given at construction time). The state may have a hint associated with it, specifying its valid range. `Action` is merely the interface to the concept of an action, as described above. Various implementations of actions exist, including `SimpleAction`. In all cases, the implementing class is responsible for storing the name of the action, the parameter type, the enabled state, the optional state type and the state and emitting the appropriate signals when these change. The implementor is responsible for filtering calls to `Action::activate` and `Action::change_state` for type safety and for the state being enabled. Probably the only useful thing to do with a `Action` is to put it inside of a `SimpleActionGroup`. # Implements [`ActionExt`](trait.ActionExt.html) Trait containing all `Action` methods. # Implementors [`Action`](struct.Action.html), [`PropertyAction`](struct.PropertyAction.html), [`SimpleAction`](struct.SimpleAction.html) Checks if `action_name` is valid. `action_name` is valid if it consists only of alphanumeric characters, plus '-' and '.'. The empty string is not a valid action name. It is an error to call this function with a non-utf8 `action_name`. `action_name` must not be `None`. ## `action_name` an potential action name # Returns `true` if `action_name` is valid Parses a detailed action name into its separate name and target components. Detailed action names can have three formats. The first format is used to represent an action name with no target value and consists of just an action name containing no whitespace nor the characters ':', '(' or ')'. For example: "app.action". The second format is used to represent an action with a target value that is a non-empty string consisting only of alphanumerics, plus '-' and '.'. In that case, the action name and target value are separated by a double colon ("::"). For example: "app.action::target". The third format is used to represent an action with any type of target value, including strings. The target value follows the action name, surrounded in parens. For example: "app.action(42)". The target value is parsed using `glib::Variant::parse`. If a tuple-typed value is desired, it must be specified in the same way, resulting in two sets of parens, for example: "app.action((1,2,3))". A string target can be specified this way as well: "app.action('target')". For strings, this third format must be used if * target value is empty or contains characters other than alphanumerics, '-' and '.'. ## `detailed_name` a detailed action name ## `action_name` the action name ## `target_value` the target value, or `None` for no target # Returns `true` if successful, else `false` with `error` set Formats a detailed action name from `action_name` and `target_value`. It is an error to call this function with an invalid action name. This function is the opposite of `Action::parse_detailed_name`. It will produce a string that can be parsed back to the `action_name` and `target_value` by that function. See that function for the types of strings that will be printed by this function. ## `action_name` a valid action name ## `target_value` a `glib::Variant` target value, or `None` # Returns a detailed format string Activates the action. `parameter` must be the correct type of parameter for the action (ie: the parameter type given at construction time). If the parameter type was `None` then `parameter` must also be `None`. If the `parameter` GVariant is floating, it is consumed. ## `parameter` the parameter to the activation Request for the state of `self` to be changed to `value`. The action must be stateful and `value` must be of the correct type. See `Action::get_state_type`. This call merely requests a change. The action may refuse to change its state or may change its state to something other than `value`. See `Action::get_state_hint`. If the `value` GVariant is floating, it is consumed. ## `value` the new state Checks if `self` is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. # Returns whether the action is enabled Queries the name of `self`. # Returns the name of the action Queries the type of the parameter that must be given when activating `self`. When activating the action using `Action::activate`, the `glib::Variant` given to that function must be of the type returned by this function. In the case that this function returns `None`, you must not give any `glib::Variant`, but `None` instead. # Returns the parameter type Queries the current state of `self`. If the action is not stateful then `None` will be returned. If the action is stateful then the type of the return value is the type given by `Action::get_state_type`. The return value (if non-`None`) should be freed with `glib::Variant::unref` when it is no longer required. # Returns the current state of the action Requests a hint about the valid range of values for the state of `self`. If `None` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. If a `glib::Variant` array is returned then each item in the array is a possible value for the state. If a `glib::Variant` pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. The return value (if non-`None`) should be freed with `glib::Variant::unref` when it is no longer required. # Returns the state range hint Queries the type of the state of `self`. If the action is stateful (e.g. created with `SimpleAction::new_stateful`) then this function returns the `glib::VariantType` of the state. This is the type of the initial value given as the state. All calls to `Action::change_state` must give a `glib::Variant` of this type and `Action::get_state` will return a `glib::Variant` of the same type. If the action is not stateful (e.g. created with `SimpleAction::new`) then this function will return `None`. In that case, `Action::get_state` will return `None` and you must not call `Action::change_state`. # Returns the state type, if the action is stateful If `action` is currently enabled. If the action is disabled then calls to `Action::activate` and `Action::change_state` have no effect. The name of the action. This is mostly meaningful for identifying the action once it has been added to a `ActionGroup`. It is immutable. The type of the parameter that must be given when activating the action. This is immutable, and may be `None` if no parameter is needed when activating the action. The state of the action, or `None` if the action is stateless. The `glib::VariantType` of the state that the action has, or `None` if the action is stateless. This is immutable. `ActionGroup` represents a group of actions. Actions can be used to expose functionality in a structured way, either from one part of a program to another, or to the outside world. Action groups are often used together with a `MenuModel` that provides additional representation data for displaying the actions to the user, e.g. in a menu. The main way to interact with the actions in a GActionGroup is to activate them with `ActionGroup::activate_action`. Activating an action may require a `glib::Variant` parameter. The required type of the parameter can be inquired with `ActionGroup::get_action_parameter_type`. Actions may be disabled, see `ActionGroup::get_action_enabled`. Activating a disabled action has no effect. Actions may optionally have a state in the form of a `glib::Variant`. The current state of an action can be inquired with `ActionGroup::get_action_state`. Activating a stateful action may change its state, but it is also possible to set the state by calling `ActionGroup::change_action_state`. As typical example, consider a text editing application which has an option to change the current font to 'bold'. A good way to represent this would be a stateful action, with a boolean state. Activating the action would toggle the state. Each action in the group has a unique name (which is a string). All method calls, except `ActionGroup::list_actions` take the name of an action as an argument. The `ActionGroup` API is meant to be the 'public' API to the action group. The calls here are exactly the interaction that 'external forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have with actions. 'Internal' APIs (ie: ones meant only to be accessed by the action group implementation) are found on subclasses. This is why you will find - for example - `ActionGroup::get_action_enabled` but not an equivalent `set` call. Signals are emitted on the action group in response to state changes on individual actions. Implementations of `ActionGroup` should provide implementations for the virtual functions `ActionGroup::list_actions` and `ActionGroup::query_action`. The other virtual functions should not be implemented - their "wrappers" are actually implemented with calls to `ActionGroup::query_action`. # Implements [`ActionGroupExt`](trait.ActionGroupExt.html) Trait containing all `ActionGroup` methods. # Implementors [`ActionGroup`](struct.ActionGroup.html), [`Application`](struct.Application.html), [`RemoteActionGroup`](struct.RemoteActionGroup.html), [`SimpleActionGroup`](struct.SimpleActionGroup.html) Emits the `ActionGroup::action-added` signal on `self`. This function should only be called by `ActionGroup` implementations. ## `action_name` the name of an action in the group Emits the `ActionGroup::action-enabled-changed` signal on `self`. This function should only be called by `ActionGroup` implementations. ## `action_name` the name of an action in the group ## `enabled` whether or not the action is now enabled Emits the `ActionGroup::action-removed` signal on `self`. This function should only be called by `ActionGroup` implementations. ## `action_name` the name of an action in the group Emits the `ActionGroup::action-state-changed` signal on `self`. This function should only be called by `ActionGroup` implementations. ## `action_name` the name of an action in the group ## `state` the new state of the named action Activate the named action within `self`. If the action is expecting a parameter, then the correct type of parameter must be given as `parameter`. If the action is expecting no parameters then `parameter` must be `None`. See `ActionGroup::get_action_parameter_type`. ## `action_name` the name of the action to activate ## `parameter` parameters to the activation Request for the state of the named action within `self` to be changed to `value`. The action must be stateful and `value` must be of the correct type. See `ActionGroup::get_action_state_type`. This call merely requests a change. The action may refuse to change its state or may change its state to something other than `value`. See `ActionGroup::get_action_state_hint`. If the `value` GVariant is floating, it is consumed. ## `action_name` the name of the action to request the change on ## `value` the new state Checks if the named action within `self` is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. ## `action_name` the name of the action to query # Returns whether or not the action is currently enabled Queries the type of the parameter that must be given when activating the named action within `self`. When activating the action using `ActionGroup::activate_action`, the `glib::Variant` given to that function must be of the type returned by this function. In the case that this function returns `None`, you must not give any `glib::Variant`, but `None` instead. The parameter type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different parameter type. ## `action_name` the name of the action to query # Returns the parameter type Queries the current state of the named action within `self`. If the action is not stateful then `None` will be returned. If the action is stateful then the type of the return value is the type given by `ActionGroup::get_action_state_type`. The return value (if non-`None`) should be freed with `glib::Variant::unref` when it is no longer required. ## `action_name` the name of the action to query # Returns the current state of the action Requests a hint about the valid range of values for the state of the named action within `self`. If `None` is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. If a `glib::Variant` array is returned then each item in the array is a possible value for the state. If a `glib::Variant` pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. The return value (if non-`None`) should be freed with `glib::Variant::unref` when it is no longer required. ## `action_name` the name of the action to query # Returns the state range hint Queries the type of the state of the named action within `self`. If the action is stateful then this function returns the `glib::VariantType` of the state. All calls to `ActionGroup::change_action_state` must give a `glib::Variant` of this type and `ActionGroup::get_action_state` will return a `glib::Variant` of the same type. If the action is not stateful then this function will return `None`. In that case, `ActionGroup::get_action_state` will return `None` and you must not call `ActionGroup::change_action_state`. The state type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different state type. ## `action_name` the name of the action to query # Returns the state type, if the action is stateful Checks if the named action exists within `self`. ## `action_name` the name of the action to check for # Returns whether the named action exists Lists the actions contained within `self`. The caller is responsible for freeing the list with `g_strfreev` when it is no longer required. # Returns a `None`-terminated array of the names of the actions in the group Queries all aspects of the named action within an `self`. This function acquires the information available from `ActionGroup::has_action`, `ActionGroup::get_action_enabled`, `ActionGroup::get_action_parameter_type`, `ActionGroup::get_action_state_type`, `ActionGroup::get_action_state_hint` and `ActionGroup::get_action_state` with a single function call. This provides two main benefits. The first is the improvement in efficiency that comes with not having to perform repeated lookups of the action in order to discover different things about it. The second is that implementing `ActionGroup` can now be done by only overriding this one virtual function. The interface provides a default implementation of this function that calls the individual functions, as required, to fetch the information. The interface also provides default implementations of those functions that call this function. All implementations, therefore, must override either this function or all of the others. If the action exists, `true` is returned and any of the requested fields (as indicated by having a non-`None` reference passed in) are filled. If the action doesn't exist, `false` is returned and the fields may or may not have been modified. ## `action_name` the name of an action in the group ## `enabled` if the action is presently enabled ## `parameter_type` the parameter type, or `None` if none needed ## `state_type` the state type, or `None` if stateless ## `state_hint` the state hint, or `None` if none ## `state` the current state, or `None` if stateless # Returns `true` if the action exists, else `false` Signals that a new action was just added to the group. This signal is emitted after the action has been added and is now visible. ## `action_name` the name of the action in `action_group` Signals that the enabled status of the named action has changed. ## `action_name` the name of the action in `action_group` ## `enabled` whether the action is enabled or not Signals that an action is just about to be removed from the group. This signal is emitted before the action is removed, so the action is still visible and can be queried from the signal handler. ## `action_name` the name of the action in `action_group` Signals that the state of the named action has changed. ## `action_name` the name of the action in `action_group` ## `value` the new value of the state The GActionMap interface is implemented by `ActionGroup` implementations that operate by containing a number of named `Action` instances, such as `SimpleActionGroup`. One useful application of this interface is to map the names of actions from various action groups to unique, prefixed names (e.g. by prepending "app." or "win."). This is the motivation for the 'Map' part of the interface name. # Implements [`ActionMapExt`](trait.ActionMapExt.html) Trait containing all `ActionMap` methods. # Implementors [`ActionMap`](struct.ActionMap.html), [`Application`](struct.Application.html), [`SimpleActionGroup`](struct.SimpleActionGroup.html) Adds an action to the `self`. If the action map already contains an action with the same name as `action` then the old action is dropped from the action map. The action map takes its own reference on `action`. ## `action` a `Action` A convenience function for creating multiple `SimpleAction` instances and adding them to a `ActionMap`. Each action is constructed as per one `ActionEntry`. ```C static void activate_quit (GSimpleAction *simple, GVariant *parameter, gpointer user_data) { exit (0); } static void activate_print_string (GSimpleAction *simple, GVariant *parameter, gpointer user_data) { g_print ("%s\n", g_variant_get_string (parameter, NULL)); } static GActionGroup * create_action_group (void) { const GActionEntry entries[] = { { "quit", activate_quit }, { "print-string", activate_print_string, "s" } }; GSimpleActionGroup *group; group = g_simple_action_group_new (); g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); return G_ACTION_GROUP (group); } ``` ## `entries` a pointer to the first item in an array of `ActionEntry` structs ## `n_entries` the length of `entries`, or -1 if `entries` is `None`-terminated ## `user_data` the user data for signal connections Looks up the action with the name `action_name` in `self`. If no such action exists, returns `None`. ## `action_name` the name of an action # Returns a `Action`, or `None` Removes the named action from the action map. If no action of this name is in the map then nothing happens. ## `action_name` the name of the action `AppInfo` and `AppLaunchContext` are used for describing and launching applications installed on the system. As of GLib 2.20, URIs will always be converted to POSIX paths (using `File::get_path`) when using `AppInfo::launch` even if the application requested an URI and not a POSIX path. For example for an desktop-file based application with Exec key `totem %U` and a single URI, `sftp://foo/file.avi`, then `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will only work if a set of suitable GIO extensions (such as gvfs 2.26 compiled with FUSE support), is available and operational; if this is not the case, the URI will be passed unmodified to the application. Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX path (in gvfs there's no FUSE mount for it); such URIs will be passed unmodified to the application. Specifically for gvfs 2.26 and later, the POSIX URI will be mapped back to the GIO URI in the `File` constructors (since gvfs implements the `Vfs` extension point). As such, if the application needs to examine the URI, it needs to use `File::get_uri` or similar on `File`. In other words, an application cannot assume that the URI passed to e.g. `File::new_for_commandline_arg` is equal to the result of `File::get_uri`. The following snippet illustrates this: ```text GFile *f; char *uri; file = g_file_new_for_commandline_arg (uri_from_commandline); uri = g_file_get_uri (file); strcmp (uri, uri_from_commandline) == 0; g_free (uri); if (g_file_has_uri_scheme (file, "cdda")) { // do something special with uri } g_object_unref (file); ``` This code will work when both `cdda://sr0/Track 1.wav` and `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the application. It should be noted that it's generally not safe for applications to rely on the format of a particular URIs. Different launcher applications (e.g. file managers) may have different ideas of what a given URI means. # Implements [`AppInfoExt`](trait.AppInfoExt.html) Trait containing all `AppInfo` methods. # Implementors [`AppInfo`](struct.AppInfo.html), [`DesktopAppInfo`](struct.DesktopAppInfo.html) Creates a new `AppInfo` from the given information. Note that for `commandline`, the quoting rules of the Exec key of the [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) are applied. For example, if the `commandline` contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from being swallowed by Exec key unquoting. See the specification for exact quoting rules. ## `commandline` the commandline to use ## `application_name` the application name, or `None` to use `commandline` ## `flags` flags that can specify details of the created `AppInfo` # Returns new `AppInfo` for given command. Gets a list of all of the applications currently registered on this system. For desktop files, this includes applications that have `NoDisplay=true` set or are excluded from display by means of `OnlyShowIn` or `NotShowIn`. See `AppInfo::should_show`. The returned list does not include applications which have the `Hidden` key set. # Returns a newly allocated `glib::List` of references to `GAppInfos`. Gets a list of all `GAppInfos` for a given content type, including the recommended and fallback `GAppInfos`. See `AppInfo::get_recommended_for_type` and `AppInfo::get_fallback_for_type`. ## `content_type` the content type to find a `AppInfo` for # Returns `glib::List` of `GAppInfos` for given `content_type` or `None` on error. Gets the default `AppInfo` for a given content type. ## `content_type` the content type to find a `AppInfo` for ## `must_support_uris` if `true`, the `AppInfo` is expected to support URIs # Returns `AppInfo` for given `content_type` or `None` on error. Gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the ':', e.g. "http", "ftp" or "sip". ## `uri_scheme` a string containing a URI scheme. # Returns `AppInfo` for given `uri_scheme` or `None` on error. Gets a list of fallback `GAppInfos` for a given content type, i.e. those applications which claim to support the given content type by MIME type subclassing and not directly. ## `content_type` the content type to find a `AppInfo` for # Returns `glib::List` of `GAppInfos` for given `content_type` or `None` on error. Gets a list of recommended `GAppInfos` for a given content type, i.e. those applications which claim to support the given content type exactly, and not by MIME type subclassing. Note that the first application of the list is the last used one, i.e. the last one for which `AppInfo::set_as_last_used_for_type` has been called. ## `content_type` the content type to find a `AppInfo` for # Returns `glib::List` of `GAppInfos` for given `content_type` or `None` on error. Utility function that launches the default application registered to handle the specified uri. Synchronous I/O is done on the uri to detect the type of the file if required. ## `uri` the uri to show ## `context` an optional `AppLaunchContext` # Returns `true` on success, `false` on error. Async version of `AppInfo::launch_default_for_uri`. This version is useful if you are interested in receiving error information in the case where the application is sandboxed and the portal may present an application chooser dialog to the user. Feature: `v2_50` ## `uri` the uri to show ## `context` an optional `AppLaunchContext` ## `cancellable` a `Cancellable` ## `callback` a `GASyncReadyCallback` to call when the request is done ## `user_data` data to pass to `callback` Finishes an asynchronous launch-default-for-uri operation. Feature: `v2_50` ## `result` a `AsyncResult` # Returns `true` if the launch was successful, `false` if `error` is set Removes all changes to the type associations done by `AppInfo::set_as_default_for_type`, `AppInfo::set_as_default_for_extension`, `AppInfo::add_supports_type` or `AppInfo::remove_supports_type`. ## `content_type` a content type Adds a content type to the application information to indicate the application is capable of opening files with the given content type. ## `content_type` a string. # Returns `true` on success, `false` on error. Obtains the information whether the `AppInfo` can be deleted. See `AppInfo::delete`. # Returns `true` if `self` can be deleted Checks if a supported content type can be removed from an application. # Returns `true` if it is possible to remove supported content types from a given `self`, `false` if not. Tries to delete a `AppInfo`. On some platforms, there may be a difference between user-defined `GAppInfos` which can be deleted, and system-wide ones which cannot. See `AppInfo::can_delete`. # Returns `true` if `self` has been deleted Creates a duplicate of a `AppInfo`. # Returns a duplicate of `self`. Checks if two `GAppInfos` are equal. Note that the check ``may not`` compare each individual field, and only does an identity check. In case detecting changes in the contents is needed, program code must additionally compare relevant fields. ## `appinfo2` the second `AppInfo`. # Returns `true` if `self` is equal to `appinfo2`. `false` otherwise. Gets the commandline with which the application will be started. # Returns a string containing the `self`'s commandline, or `None` if this information is not available Gets a human-readable description of an installed application. # Returns a string containing a description of the application `self`, or `None` if none. Gets the display name of the application. The display name is often more descriptive to the user than the name itself. # Returns the display name of the application for `self`, or the name if no display name is available. Gets the executable's name for the installed application. # Returns a string containing the `self`'s application binaries name Gets the icon for the application. # Returns the default `Icon` for `self` or `None` if there is no default icon. Gets the ID of an application. An id is a string that identifies the application. The exact format of the id is platform dependent. For instance, on Unix this is the desktop file id from the xdg menu specification. Note that the returned ID may be `None`, depending on how the `self` has been constructed. # Returns a string containing the application's ID. Gets the installed name of the application. # Returns the name of the application for `self`. Retrieves the list of content types that `app_info` claims to support. If this information is not provided by the environment, this function will return `None`. This function does not take in consideration associations added with `AppInfo::add_supports_type`, but only those exported directly by the application. # Returns a list of content types. Launches the application. Passes `files` to the launched application as arguments, using the optional `context` to get information about the details of the launcher (like what screen it is on). On error, `error` will be set accordingly. To launch the application without arguments pass a `None` `files` list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using `AppInfo::launch_uris` instead. The launched application inherits the environment of the launching process, but it can be modified with `AppLaunchContextExt::setenv` and `AppLaunchContextExt::unsetenv`. On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` environment variable with the path of the launched desktop file and `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, should it be inherited by further processes. The `DISPLAY` and `DESKTOP_STARTUP_ID` environment variables are also set, based on information provided in `context`. ## `files` a `glib::List` of `File` objects ## `context` a `AppLaunchContext` or `None` # Returns `true` on successful launch, `false` otherwise. Launches the application. This passes the `uris` to the launched application as arguments, using the optional `context` to get information about the details of the launcher (like what screen it is on). On error, `error` will be set accordingly. To launch the application without arguments pass a `None` `uris` list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. ## `uris` a `glib::List` containing URIs to launch. ## `context` a `AppLaunchContext` or `None` # Returns `true` on successful launch, `false` otherwise. Removes a supported type from an application, if possible. ## `content_type` a string. # Returns `true` on success, `false` on error. Sets the application as the default handler for the given file extension. ## `extension` a string containing the file extension (without the dot). # Returns `true` on success, `false` on error. Sets the application as the default handler for a given type. ## `content_type` the content type. # Returns `true` on success, `false` on error. Sets the application as the last used application for a given type. This will make the application appear as first in the list returned by `AppInfo::get_recommended_for_type`, regardless of the default application for that content type. ## `content_type` the content type. # Returns `true` on success, `false` on error. Checks if the application info should be shown in menus that list available applications. # Returns `true` if the `self` should be shown, `false` otherwise. Checks if the application accepts files as arguments. # Returns `true` if the `self` supports files. Checks if the application supports reading files and directories from URIs. # Returns `true` if the `self` supports URIs. `AppInfoMonitor` is a very simple object used for monitoring the app info database for changes (ie: newly installed or removed applications). Call `AppInfoMonitor::get` to get a `AppInfoMonitor` and connect to the "changed" signal. In the usual case, applications should try to make note of the change (doing things like invalidating caches) but not act on it. In particular, applications should avoid making calls to `AppInfo` APIs in response to the change signal, deferring these until the time that the data is actually required. The exception to this case is when application information is actually being displayed on the screen (eg: during a search or when the list of all applications is shown). The reason for this is that changes to the list of installed applications often come in groups (like during system updates) and rescanning the list on every change is pointless and expensive. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Gets the `AppInfoMonitor` for the current thread-default main context. The `AppInfoMonitor` will emit a "changed" signal in the thread-default main context whenever the list of installed applications (as reported by `AppInfo::get_all`) may have changed. You must only call `gobject::ObjectExt::unref` on the return value from under the same main context as you created it. # Returns a reference to a `AppInfoMonitor` Signal emitted when the app info database for changes (ie: newly installed or removed applications). Integrating the launch with the launching application. This is used to handle for instance startup notification and launching the new application on the same screen as the launching window. # Implements [`AppLaunchContextExt`](trait.AppLaunchContextExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `AppLaunchContext` methods. # Implementors [`AppLaunchContext`](struct.AppLaunchContext.html) Creates a new application launch context. This is not normally used, instead you instantiate a subclass of this, such as ``GdkAppLaunchContext``. # Returns a `AppLaunchContext`. Gets the display string for the `self`. This is used to ensure new applications are started on the same display as the launching application, by setting the `DISPLAY` environment variable. ## `info` a `AppInfo` ## `files` a `glib::List` of `File` objects # Returns a display string for the display. Gets the complete environment variable list to be passed to the child process when `self` is used to launch an application. This is a `None`-terminated array of strings, where each string has the form `KEY=VALUE`. # Returns the child's environment Initiates startup notification for the application and returns the `DESKTOP_STARTUP_ID` for the launched operation, if supported. Startup notification IDs are defined in the [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"). ## `info` a `AppInfo` ## `files` a `glib::List` of of `File` objects # Returns a startup notification ID for the application, or `None` if not supported. Called when an application has failed to launch, so that it can cancel the application startup notification started in `AppLaunchContextExt::get_startup_notify_id`. ## `startup_notify_id` the startup notification id that was returned by `AppLaunchContextExt::get_startup_notify_id`. Arranges for `variable` to be set to `value` in the child's environment when `self` is used to launch an application. ## `variable` the environment variable to set ## `value` the value for to set the variable to. Arranges for `variable` to be unset in the child's environment when `self` is used to launch an application. ## `variable` the environment variable to remove The ::launch-failed signal is emitted when a `AppInfo` launch fails. The startup notification id is provided, so that the launcher can cancel the startup notification. ## `startup_notify_id` the startup notification id for the failed launch The ::launched signal is emitted when a `AppInfo` is successfully launched. The `platform_data` is an GVariant dictionary mapping strings to variants (ie a{sv}), which contains additional, platform-specific data about this launch. On UNIX, at least the "pid" and "startup-notification-id" keys will be present. ## `info` the `AppInfo` that was just launched ## `platform_data` additional platform-specific data for this launch A `Application` is the foundation of an application. It wraps some low-level platform-specific services and is intended to act as the foundation for higher-level application classes such as ``GtkApplication`` or `MxApplication`. In general, you should not use this class outside of a higher level framework. GApplication provides convenient life cycle management by maintaining a "use count" for the primary application instance. The use count can be changed using `ApplicationExt::hold` and `ApplicationExt::release`. If it drops to zero, the application exits. Higher-level classes such as ``GtkApplication`` employ the use count to ensure that the application stays alive as long as it has any opened windows. Another feature that GApplication (optionally) provides is process uniqueness. Applications can make use of this functionality by providing a unique application ID. If given, only one application with this ID can be running at a time per session. The session concept is platform-dependent, but corresponds roughly to a graphical desktop login. When your application is launched again, its arguments are passed through platform communication to the already running program. The already running instance of the program is called the "primary instance"; for non-unique applications this is the always the current instance. On Linux, the D-Bus session bus is used for communication. The use of `Application` differs from some other commonly-used uniqueness libraries (such as libunique) in important ways. The application is not expected to manually register itself and check if it is the primary instance. Instead, the `main` function of a `Application` should do very little more than instantiating the application instance, possibly connecting signal handlers, then calling `Application::run`. All checks for uniqueness are done internally. If the application is the primary instance then the startup signal is emitted and the mainloop runs. If the application is not the primary instance then a signal is sent to the primary instance and `Application::run` promptly returns. See the code examples below. If used, the expected form of an application identifier is the same as that of of a [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html`message`-protocol-names-bus). Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`, `org._7_zip.Archiver`. For details on valid application identifiers, see `Application::id_is_valid`. On Linux, the application identifier is claimed as a well-known bus name on the user's session bus. This means that the uniqueness of your application is scoped to the current session. It also means that your application may provide additional services (through registration of other object paths) at that bus name. The registration of these object paths should be done with the shared GDBus session bus. Note that due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before `Application` attempts to acquire the bus name of your application (which happens in `ApplicationExt::register`). Unfortunately, this means that you cannot use `ApplicationExt::get_is_remote` to decide if you want to register object paths. GApplication also implements the `ActionGroup` and `ActionMap` interfaces and lets you easily export actions by adding them with `ActionMap::add_action`. When invoking an action by calling `ActionGroup::activate_action` on the application, it is always invoked in the primary instance. The actions are also exported on the session bus, and GIO provides the `DBusActionGroup` wrapper to conveniently access them remotely. GIO provides a `DBusMenuModel` wrapper for remote access to exported `GMenuModels`. There is a number of different entry points into a GApplication: - via 'Activate' (i.e. just starting the application) - via 'Open' (i.e. opening some files) - by handling a command-line - via activating an action The `Application::startup` signal lets you handle the application initialization for all of these in a single place. Regardless of which of these entry points is used to start the application, GApplication passes some "platform data from the launching instance to the primary instance, in the form of a `glib::Variant` dictionary mapping strings to variants. To use platform data, override the `before_emit` or `after_emit` virtual functions in your `Application` subclass. When dealing with `ApplicationCommandLine` objects, the platform data is directly available via `ApplicationCommandLineExt::get_cwd`, `ApplicationCommandLineExt::get_environ` and `ApplicationCommandLineExt::get_platform_data`. As the name indicates, the platform data may vary depending on the operating system, but it always includes the current directory (key "cwd"), and optionally the environment (ie the set of environment variables and their values) of the calling process (key "environ"). The environment is only added to the platform data if the `ApplicationFlags::SendEnvironment` flag is set. `Application` subclasses can add their own platform data by overriding the `add_platform_data` virtual function. For instance, ``GtkApplication`` adds startup notification data in this way. To parse commandline arguments you may handle the `Application::command-line` signal or override the `local_command_line` vfunc, to parse them in either the primary instance or the local instance, respectively. For an example of opening files with a GApplication, see [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c). For an example of using actions with GApplication, see [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c). For an example of using extra D-Bus hooks with GApplication, see [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c). # Implements [`ApplicationExt`](trait.ApplicationExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html), [`ActionMapExt`](trait.ActionMapExt.html), [`ApplicationExtManual`](prelude/trait.ApplicationExtManual.html) Trait containing all `Application` methods. # Implementors [`Application`](struct.Application.html) Creates a new `Application` instance. If non-`None`, the application id must be valid. See `Application::id_is_valid`. If no application ID is given then some features of `Application` (most notably application uniqueness) will be disabled. ## `application_id` the application id ## `flags` the application flags # Returns a new `Application` instance Returns the default `Application` instance for this process. Normally there is only one `Application` per process and it becomes the default when it is created. You can exercise more control over this by using `ApplicationExt::set_default`. If there is no default application then `None` is returned. # Returns the default application for this process, or `None` Checks if `application_id` is a valid application identifier. A valid ID is required for calls to `Application::new` and `ApplicationExt::set_application_id`. Application identifiers follow the same format as [D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html`message`-protocol-names-bus). For convenience, the restrictions on application identifiers are reproduced here: - Application identifiers are composed of 1 or more elements separated by a period (`.`) character. All elements must contain at least one character. - Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`, with `-` discouraged in new application identifiers. Each element must not begin with a digit. - Application identifiers must contain at least one `.` (period) character (and thus at least two elements). - Application identifiers must not begin with a `.` (period) character. - Application identifiers must not exceed 255 characters. Note that the hyphen (`-`) character is allowed in application identifiers, but is problematic or not allowed in various specifications and APIs that refer to D-Bus, such as [Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html`identifiers`), the [`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html`dbus`), and the convention that an application's "main" interface and object path resemble its application identifier and bus name. To avoid situations that require special-case handling, it is recommended that new application identifiers consistently replace hyphens with underscores. Like D-Bus interface names, application identifiers should start with the reversed DNS domain name of the author of the interface (in lower-case), and it is conventional for the rest of the application identifier to consist of words run together, with initial capital letters. As with D-Bus interface names, if the author's DNS domain name contains hyphen/minus characters they should be replaced by underscores, and if it contains leading digits they should be escaped by prepending an underscore. For example, if the owner of 7-zip.org used an application identifier for an archiving application, it might be named `org._7_zip.Archiver`. ## `application_id` a potential application identifier # Returns `true` if `application_id` is valid Activates the application. In essence, this results in the `Application::activate` signal being emitted in the primary instance. The application must be registered before calling this function. Add an option to be handled by `self`. Calling this function is the equivalent of calling `ApplicationExt::add_main_option_entries` with a single `glib::OptionEntry` that has its arg_data member set to `None`. The parsed arguments will be packed into a `glib::VariantDict` which is passed to `Application::handle-local-options`. If `ApplicationFlags::HandlesCommandLine` is set, then it will also be sent to the primary instance. See `ApplicationExt::add_main_option_entries` for more details. See `glib::OptionEntry` for more documentation of the arguments. ## `long_name` the long name of an option used to specify it in a commandline ## `short_name` the short name of an option ## `flags` flags from `glib::OptionFlags` ## `arg` the type of the option, as a `glib::OptionArg` ## `description` the description for the option in `--help` output ## `arg_description` the placeholder to use for the extra argument parsed by the option in `--help` output Adds main option entries to be handled by `self`. This function is comparable to `glib::OptionContext::add_main_entries`. After the commandline arguments are parsed, the `Application::handle-local-options` signal will be emitted. At this point, the application can inspect the values pointed to by `arg_data` in the given `GOptionEntrys`. Unlike `glib::OptionContext`, `Application` supports giving a `None` `arg_data` for a non-callback `glib::OptionEntry`. This results in the argument in question being packed into a `glib::VariantDict` which is also passed to `Application::handle-local-options`, where it can be inspected and modified. If `ApplicationFlags::HandlesCommandLine` is set, then the resulting dictionary is sent to the primary instance, where `ApplicationCommandLineExt::get_options_dict` will return it. This "packing" is done according to the type of the argument -- booleans for normal flags, strings for strings, bytestrings for filenames, etc. The packing only occurs if the flag is given (ie: we do not pack a "false" `glib::Variant` in the case that a flag is missing). In general, it is recommended that all commandline arguments are parsed locally. The options dictionary should then be used to transmit the result of the parsing to the primary instance, where `glib::VariantDict::lookup` can be used. For local options, it is possible to either use `arg_data` in the usual way, or to consult (and potentially remove) the option from the options dictionary. This function is new in GLib 2.40. Before then, the only real choice was to send all of the commandline arguments (options and all) to the primary instance for handling. `Application` ignored them completely on the local side. Calling this function "opts in" to the new behaviour, and in particular, means that unrecognised options will be treated as errors. Unrecognised options have never been ignored when `ApplicationFlags::HandlesCommandLine` is unset. If `Application::handle-local-options` needs to see the list of filenames, then the use of `G_OPTION_REMAINING` is recommended. If `arg_data` is `None` then `G_OPTION_REMAINING` can be used as a key into the options dictionary. If you do use `G_OPTION_REMAINING` then you need to handle these arguments for yourself because once they are consumed, they will no longer be visible to the default handling (which treats them as filenames to be opened). It is important to use the proper GVariant format when retrieving the options with `glib::VariantDict::lookup`: - for `glib::OptionArg::None`, use b - for `glib::OptionArg::String`, use &s - for `glib::OptionArg::Int`, use i - for `glib::OptionArg::Int64`, use x - for `glib::OptionArg::Double`, use d - for `glib::OptionArg::Filename`, use ^ay - for `glib::OptionArg::StringArray`, use &as - for `glib::OptionArg::FilenameArray`, use ^aay ## `entries` a `None`-terminated list of `GOptionEntrys` Adds a `glib::OptionGroup` to the commandline handling of `self`. This function is comparable to `glib::OptionContext::add_group`. Unlike `ApplicationExt::add_main_option_entries`, this function does not deal with `None` `arg_data` and never transmits options to the primary instance. The reason for that is because, by the time the options arrive at the primary instance, it is typically too late to do anything with them. Taking the GTK option group as an example: GTK will already have been initialised by the time the `Application::command-line` handler runs. In the case that this is not the first-running instance of the application, the existing instance may already have been running for a very long time. This means that the options from `glib::OptionGroup` are only really usable in the case that the instance of the application being run is the first instance. Passing options like `--display=` or `--gdk-debug=` on future runs will have no effect on the existing primary instance. Calling this function will cause the options in the supplied option group to be parsed, but it does not cause you to be "opted in" to the new functionality whereby unrecognised options are rejected even if `ApplicationFlags::HandlesCommandLine` was given. ## `group` a `glib::OptionGroup` Marks `self` as busy (see `ApplicationExt::mark_busy`) while `property` on `object` is `true`. The binding holds a reference to `self` while it is active, but not to `object`. Instead, the binding is destroyed when `object` is finalized. Feature: `v2_44` ## `object` a `gobject::Object` ## `property` the name of a boolean property of `object` Gets the unique identifier for `self`. # Returns the identifier for `self`, owned by `self` Gets the `DBusConnection` being used by the application, or `None`. If `Application` is using its D-Bus backend then this function will return the `DBusConnection` being used for uniqueness and communication with the desktop environment and other instances of the application. If `Application` is not using D-Bus then this function will return `None`. This includes the situation where the D-Bus backend would normally be in use but we were unable to connect to the bus. This function must not be called before the application has been registered. See `ApplicationExt::get_is_registered`. # Returns a `DBusConnection`, or `None` Gets the D-Bus object path being used by the application, or `None`. If `Application` is using its D-Bus backend then this function will return the D-Bus object path that `Application` is using. If the application is the primary instance then there is an object published at this path. If the application is not the primary instance then the result of this function is undefined. If `Application` is not using D-Bus then this function will return `None`. This includes the situation where the D-Bus backend would normally be in use but we were unable to connect to the bus. This function must not be called before the application has been registered. See `ApplicationExt::get_is_registered`. # Returns the object path, or `None` Gets the flags for `self`. See `ApplicationFlags`. # Returns the flags for `self` Gets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to `ApplicationExt::release` before the application stops running. # Returns the timeout, in milliseconds Gets the application's current busy state, as set through `ApplicationExt::mark_busy` or `ApplicationExt::bind_busy_property`. Feature: `v2_44` # Returns `true` if `self` is currenty marked as busy Checks if `self` is registered. An application is registered if `ApplicationExt::register` has been successfully called. # Returns `true` if `self` is registered Checks if `self` is remote. If `self` is remote then it means that another instance of application already exists (the 'primary' instance). Calls to perform actions on `self` will result in the actions being performed by the primary instance. The value of this property cannot be accessed before `ApplicationExt::register` has been called. See `ApplicationExt::get_is_registered`. # Returns `true` if `self` is remote Gets the resource base path of `self`. See `ApplicationExt::set_resource_base_path` for more information. # Returns the base resource path, if one is set Increases the use count of `self`. Use this function to indicate that the application has a reason to continue to run. For example, `ApplicationExt::hold` is called by GTK+ when a toplevel window is on the screen. To cancel the hold, call `ApplicationExt::release`. Increases the busy count of `self`. Use this function to indicate that the application is busy, for instance while a long running operation is pending. The busy state will be exposed to other processes, so a session shell will use that information to indicate the state to the user (e.g. with a spinner). To cancel the busy indication, use `ApplicationExt::unmark_busy`. Opens the given files. In essence, this results in the `Application::open` signal being emitted in the primary instance. `n_files` must be greater than zero. `hint` is simply passed through to the ::open signal. It is intended to be used by applications that have multiple modes for opening files (eg: "view" vs "edit", etc). Unless you have a need for this functionality, you should use "". The application must be registered before calling this function and it must have the `ApplicationFlags::HandlesOpen` flag set. ## `files` an array of `GFiles` to open ## `n_files` the length of the `files` array ## `hint` a hint (or ""), but never `None` Immediately quits the application. Upon return to the mainloop, `Application::run` will return, calling only the 'shutdown' function before doing so. The hold count is ignored. Take care if your code has called `ApplicationExt::hold` on the application and is therefore still expecting it to exist. (Note that you may have called `ApplicationExt::hold` indirectly, for example through `gtk_application_add_window`.) The result of calling `Application::run` again after it returns is unspecified. Attempts registration of the application. This is the point at which the application discovers if it is the primary instance or merely acting as a remote for an already-existing primary instance. This is implemented by attempting to acquire the application identifier as a unique bus name on the session bus using GDBus. If there is no application ID or if `ApplicationFlags::NonUnique` was given, then this process will always become the primary instance. Due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before calling this function. If the application has already been registered then `true` is returned with no work performed. The `Application::startup` signal is emitted if registration succeeds and `self` is the primary instance (including the non-unique case). In the event of an error (such as `cancellable` being cancelled, or a failure to connect to the session bus), `false` is returned and `error` is set appropriately. Note: the return value of this function is not an indicator that this instance is or is not the primary instance of the application. See `ApplicationExt::get_is_remote` for that. ## `cancellable` a `Cancellable`, or `None` # Returns `true` if registration succeeded Decrease the use count of `self`. When the use count reaches zero, the application will stop running. Never call this function except to cancel the effect of a previous call to `ApplicationExt::hold`. Runs the application. This function is intended to be run from `main` and its return value is intended to be returned by `main`. Although you are expected to pass the `argc`, `argv` parameters from `main` to this function, it is possible to pass `None` if `argv` is not available or commandline handling is not required. Note that on Windows, `argc` and `argv` are ignored, and `g_win32_get_command_line` is called internally (for proper support of Unicode commandline arguments). `Application` will attempt to parse the commandline arguments. You can add commandline flags to the list of recognised options by way of `ApplicationExt::add_main_option_entries`. After this, the `Application::handle-local-options` signal is emitted, from which the application can inspect the values of its `GOptionEntrys`. `Application::handle-local-options` is a good place to handle options such as `--version`, where an immediate reply from the local process is desired (instead of communicating with an already-running instance). A `Application::handle-local-options` handler can stop further processing by returning a non-negative value, which then becomes the exit status of the process. What happens next depends on the flags: if `ApplicationFlags::HandlesCommandLine` was specified then the remaining commandline arguments are sent to the primary instance, where a `Application::command-line` signal is emitted. Otherwise, the remaining commandline arguments are assumed to be a list of files. If there are no files listed, the application is activated via the `Application::activate` signal. If there are one or more files, and `ApplicationFlags::HandlesOpen` was specified then the files are opened via the `Application::open` signal. If you are interested in doing more complicated local handling of the commandline then you should implement your own `Application` subclass and override `local_command_line`. In this case, you most likely want to return `true` from your `local_command_line` implementation to suppress the default handling. See [gapplication-example-cmdline2.c][gapplication-example-cmdline2] for an example. If, after the above is done, the use count of the application is zero then the exit status is returned immediately. If the use count is non-zero then the default main context is iterated until the use count falls to zero, at which point 0 is returned. If the `ApplicationFlags::IsService` flag is set, then the service will run for as much as 10 seconds with a use count of zero while waiting for the message that caused the activation to arrive. After that, if the use count falls to zero the application will exit immediately, except in the case that `ApplicationExt::set_inactivity_timeout` is in use. This function sets the prgname (`g_set_prgname`), if not already set, to the basename of argv[0]. Much like `glib::MainLoop::run`, this function will acquire the main context for the duration that the application is running. Since 2.40, applications that are not explicitly flagged as services or launchers (ie: neither `ApplicationFlags::IsService` or `ApplicationFlags::IsLauncher` are given as flags) will check (from the default handler for local_command_line) if "--gapplication-service" was given in the command line. If this flag is present then normal commandline processing is interrupted and the `ApplicationFlags::IsService` flag is set. This provides a "compromise" solution whereby running an application directly from the commandline will invoke it in the normal way (which can be useful for debugging) while still allowing applications to be D-Bus activated in service mode. The D-Bus service file should invoke the executable with "--gapplication-service" as the sole commandline argument. This approach is suitable for use by most graphical applications but should not be used from applications like editors that need precise control over when processes invoked via the commandline will exit and what their exit status will be. ## `argc` the argc from `main` (or 0 if `argv` is `None`) ## `argv` the argv from `main`, or `None` # Returns the exit status Sends a notification on behalf of `self` to the desktop shell. There is no guarantee that the notification is displayed immediately, or even at all. Notifications may persist after the application exits. It will be D-Bus-activated when the notification or one of its actions is activated. Modifying `notification` after this call has no effect. However, the object can be reused for a later call to this function. `id` may be any string that uniquely identifies the event for the application. It does not need to be in any special format. For example, "new-message" might be appropriate for a notification about new messages. If a previous notification was sent with the same `id`, it will be replaced with `notification` and shown again as if it was a new notification. This works even for notifications sent from a previous execution of the application, as long as `id` is the same string. `id` may be `None`, but it is impossible to replace or withdraw notifications without an id. If `notification` is no longer relevant, it can be withdrawn with `ApplicationExt::withdraw_notification`. ## `id` id of the notification, or `None` ## `notification` the `Notification` to send Sets the unique identifier for `self`. The application id can only be modified if `self` has not yet been registered. If non-`None`, the application id must be valid. See `Application::id_is_valid`. ## `application_id` the identifier for `self` Sets or unsets the default application for the process, as returned by `Application::get_default`. This function does not take its own reference on `self`. If `self` is destroyed then the default application will revert back to `None`. Sets the flags for `self`. The flags can only be modified if `self` has not yet been registered. See `ApplicationFlags`. ## `flags` the flags for `self` Sets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to `ApplicationExt::release` before the application stops running. This call has no side effects of its own. The value set here is only used for next time `ApplicationExt::release` drops the use count to zero. Any timeouts currently in progress are not impacted. ## `inactivity_timeout` the timeout, in milliseconds Adds a description to the `self` option context. See `glib::OptionContext::set_description` for more information. Feature: `v2_56` ## `description` a string to be shown in `--help` output after the list of options, or `None` Sets the parameter string to be used by the commandline handling of `self`. This function registers the argument to be passed to `glib::OptionContext::new` when the internal `glib::OptionContext` of `self` is created. See `glib::OptionContext::new` for more information about `parameter_string`. Feature: `v2_56` ## `parameter_string` a string which is displayed in the first line of `--help` output, after the usage summary `programname [OPTION...]`. Adds a summary to the `self` option context. See `glib::OptionContext::set_summary` for more information. Feature: `v2_56` ## `summary` a string to be shown in `--help` output before the list of options, or `None` Sets (or unsets) the base resource path of `self`. The path is used to automatically load various [application resources][gresource] such as menu layouts and action descriptions. The various types of resources will be found at fixed names relative to the given base path. By default, the resource base path is determined from the application ID by prefixing '/' and replacing each '.' with '/'. This is done at the time that the `Application` object is constructed. Changes to the application ID after that point will not have an impact on the resource base path. As an example, if the application has an ID of "org.example.app" then the default resource base path will be "/org/example/app". If this is a ``GtkApplication`` (and you have not manually changed the path) then Gtk will then search for the menus of the application at "/org/example/app/gtk/menus.ui". See `Resource` for more information about adding resources to your application. You can disable automatic resource loading functionality by setting the path to `None`. Changing the resource base path once the application is running is not recommended. The point at which the resource path is consulted for forming paths for various purposes is unspecified. When writing a sub-class of `Application` you should either set the `Application:resource-base-path` property at construction time, or call this function during the instance initialization. Alternatively, you can call this function in the `ApplicationClass.startup` virtual function, before chaining up to the parent implementation. ## `resource_path` the resource path to use Destroys a binding between `property` and the busy state of `self` that was previously created with `ApplicationExt::bind_busy_property`. Feature: `v2_44` ## `object` a `gobject::Object` ## `property` the name of a boolean property of `object` Decreases the busy count of `self`. When the busy count reaches zero, the new state will be propagated to other processes. This function must only be called to cancel the effect of a previous call to `ApplicationExt::mark_busy`. Withdraws a notification that was sent with `ApplicationExt::send_notification`. This call does nothing if a notification with `id` doesn't exist or the notification was never sent. This function works even for notifications sent in previous executions of this application, as long `id` is the same as it was for the sent notification. Note that notifications are dismissed when the user clicks on one of the buttons in a notification or triggers its default action, so there is no need to explicitly withdraw the notification in that case. ## `id` id of a previously sent notification The ::activate signal is emitted on the primary instance when an activation occurs. See `ApplicationExt::activate`. The ::command-line signal is emitted on the primary instance when a commandline is not handled locally. See `Application::run` and the `ApplicationCommandLine` documentation for more information. ## `command_line` a `ApplicationCommandLine` representing the passed commandline # Returns An integer that is set as the exit status for the calling process. See `ApplicationCommandLineExt::set_exit_status`. The ::handle-local-options signal is emitted on the local instance after the parsing of the commandline options has occurred. You can add options to be recognised during commandline option parsing using `ApplicationExt::add_main_option_entries` and `ApplicationExt::add_option_group`. Signal handlers can inspect `options` (along with values pointed to from the `arg_data` of an installed `GOptionEntrys`) in order to decide to perform certain actions, including direct local handling (which may be useful for options like --version). In the event that the application is marked `ApplicationFlags::HandlesCommandLine` the "normal processing" will send the `options` dictionary to the primary instance where it can be read with `ApplicationCommandLineExt::get_options_dict`. The signal handler can modify the dictionary before returning, and the modified dictionary will be sent. In the event that `ApplicationFlags::HandlesCommandLine` is not set, "normal processing" will treat the remaining uncollected command line arguments as filenames or URIs. If there are no arguments, the application is activated by `ApplicationExt::activate`. One or more arguments results in a call to `ApplicationExt::open`. If you want to handle the local commandline arguments for yourself by converting them to calls to `ApplicationExt::open` or `ActionGroup::activate_action` then you must be sure to register the application first. You should probably not call `ApplicationExt::activate` for yourself, however: just return -1 and allow the default handler to do it for you. This will ensure that the `--gapplication-service` switch works properly (i.e. no activation in that case). Note that this signal is emitted from the default implementation of `local_command_line`. If you override that function and don't chain up then this signal will never be emitted. You can override `local_command_line` if you need more powerful capabilities than what is provided here, but this should not normally be required. ## `options` the options dictionary # Returns an exit code. If you have handled your options and want to exit the process, return a non-negative option, 0 for success, and a positive value for failure. To continue, return -1 to let the default option processing continue. The ::open signal is emitted on the primary instance when there are files to open. See `ApplicationExt::open` for more information. ## `files` an array of `GFiles` ## `n_files` the length of `files` ## `hint` a hint provided by the calling instance The ::shutdown signal is emitted only on the registered primary instance immediately after the main loop terminates. The ::startup signal is emitted on the primary instance immediately after registration. See `ApplicationExt::register`. Whether the application is currently marked as busy through `ApplicationExt::mark_busy` or `ApplicationExt::bind_busy_property`. Feature: `v2_44` `ApplicationCommandLine` represents a command-line invocation of an application. It is created by `Application` and emitted in the `Application::command-line` signal and virtual function. The class contains the list of arguments that the program was invoked with. It is also possible to query if the commandline invocation was local (ie: the current process is running in direct response to the invocation) or remote (ie: some other process forwarded the commandline to this process). The GApplicationCommandLine object can provide the `argc` and `argv` parameters for use with the `glib::OptionContext` command-line parsing API, with the `ApplicationCommandLineExt::get_arguments` function. See [gapplication-example-cmdline3.c][gapplication-example-cmdline3] for an example. The exit status of the originally-invoked process may be set and messages can be printed to stdout or stderr of that process. The lifecycle of the originally-invoked process is tied to the lifecycle of this object (ie: the process exits when the last reference is dropped). The main use for `ApplicationCommandLine` (and the `Application::command-line` signal) is 'Emacs server' like use cases: You can set the `EDITOR` environment variable to have e.g. git use your favourite editor to edit commit messages, and if you already have an instance of the editor running, the editing will happen in the running instance, instead of opening a new one. An important aspect of this use case is that the process that gets started by git does not return until the editing is done. Normally, the commandline is completely handled in the `Application::command-line` handler. The launching instance exits once the signal handler in the primary instance has returned, and the return value of the signal handler becomes the exit status of the launching instance. ```C static int command_line (GApplication *application, GApplicationCommandLine *cmdline) { gchar **argv; gint argc; gint i; argv = g_application_command_line_get_arguments (cmdline, &argc); g_application_command_line_print (cmdline, "This text is written back\n" "to stdout of the caller\n"); for (i = 0; i < argc; i++) g_print ("argument %d: %s\n", i, argv[i]); g_strfreev (argv); return 0; } ``` The complete example can be found here: [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c) In more complicated cases, the handling of the comandline can be split between the launcher and the primary instance. ```C static gboolean test_local_cmdline (GApplication *application, gchar ***arguments, gint *exit_status) { gint i, j; gchar **argv; argv = *arguments; i = 1; while (argv[i]) { if (g_str_has_prefix (argv[i], "--local-")) { g_print ("handling argument %s locally\n", argv[i]); g_free (argv[i]); for (j = i; argv[j]; j++) argv[j] = argv[j + 1]; } else { g_print ("not handling argument %s locally\n", argv[i]); i++; } } *exit_status = 0; return FALSE; } static void test_application_class_init (TestApplicationClass *class) { G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline; ... } ``` In this example of split commandline handling, options that start with `--local-` are handled locally, all other options are passed to the `Application::command-line` handler which runs in the primary instance. The complete example can be found here: [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c) If handling the commandline requires a lot of work, it may be better to defer it. ```C static gboolean my_cmdline_handler (gpointer data) { GApplicationCommandLine *cmdline = data; // do the heavy lifting in an idle g_application_command_line_set_exit_status (cmdline, 0); g_object_unref (cmdline); // this releases the application return G_SOURCE_REMOVE; } static int command_line (GApplication *application, GApplicationCommandLine *cmdline) { // keep the application running until we are done with this commandline g_application_hold (application); g_object_set_data_full (G_OBJECT (cmdline), "application", application, (GDestroyNotify)g_application_release); g_object_ref (cmdline); g_idle_add (my_cmdline_handler, cmdline); return 0; } ``` In this example the commandline is not completely handled before the `Application::command-line` handler returns. Instead, we keep a reference to the `ApplicationCommandLine` object and handle it later (in this example, in an idle). Note that it is necessary to hold the application until you are done with the commandline. The complete example can be found here: [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c) # Implements [`ApplicationCommandLineExt`](trait.ApplicationCommandLineExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `ApplicationCommandLine` methods. # Implementors [`ApplicationCommandLine`](struct.ApplicationCommandLine.html) Creates a `File` corresponding to a filename that was given as part of the invocation of `self`. This differs from `File::new_for_commandline_arg` in that it resolves relative pathnames using the current working directory of the invoking process rather than the local process. ## `arg` an argument from `self` # Returns a new `File` Gets the list of arguments that was passed on the command line. The strings in the array may contain non-UTF-8 data on UNIX (such as filenames or arguments given in the system locale) but are always in UTF-8 on Windows. If you wish to use the return value with `glib::OptionContext`, you must use `glib::OptionContext::parse_strv`. The return value is `None`-terminated and should be freed using `g_strfreev`. ## `argc` the length of the arguments array, or `None` # Returns the string array containing the arguments (the argv) Gets the working directory of the command line invocation. The string may contain non-utf8 data. It is possible that the remote application did not send a working directory, so this may be `None`. The return value should not be modified or freed and is valid for as long as `self` exists. # Returns the current directory, or `None` Gets the contents of the 'environ' variable of the command line invocation, as would be returned by `g_get_environ`, ie as a `None`-terminated list of strings in the form 'NAME=VALUE'. The strings may contain non-utf8 data. The remote application usually does not send an environment. Use `ApplicationFlags::SendEnvironment` to affect that. Even with this flag set it is possible that the environment is still not available (due to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as `self` exists. See `ApplicationCommandLineExt::getenv` if you are only interested in the value of a single environment variable. # Returns the environment strings, or `None` if they were not sent Gets the exit status of `self`. See `ApplicationCommandLineExt::set_exit_status` for more information. # Returns the exit status Determines if `self` represents a remote invocation. # Returns `true` if the invocation was remote Gets the options there were passed to `g_application_command_line`. If you did not override `local_command_line` then these are the same options that were parsed according to the `GOptionEntrys` added to the application with `ApplicationExt::add_main_option_entries` and possibly modified from your GApplication::handle-local-options handler. If no options were sent then an empty dictionary is returned so that you don't need to check for `None`. # Returns a `glib::VariantDict` with the options Gets the platform data associated with the invocation of `self`. This is a `glib::Variant` dictionary containing information about the context in which the invocation occurred. It typically contains information like the current working directory and the startup notification ID. For local invocation, it will be `None`. # Returns the platform data, or `None` Gets the stdin of the invoking process. The `InputStream` can be used to read data passed to the standard input of the invoking process. This doesn't work on all platforms. Presently, it is only available on UNIX when using a DBus daemon capable of passing file descriptors. If stdin is not available then `None` will be returned. In the future, support may be expanded to other platforms. You must only call this function once per commandline invocation. # Returns a `InputStream` for stdin Gets the value of a particular environment variable of the command line invocation, as would be returned by `g_getenv`. The strings may contain non-utf8 data. The remote application usually does not send an environment. Use `ApplicationFlags::SendEnvironment` to affect that. Even with this flag set it is possible that the environment is still not available (due to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as `self` exists. ## `name` the environment variable to get # Returns the value of the variable, or `None` if unset or unsent Formats a message and prints it using the stdout print handler in the invoking process. If `self` is a local invocation then this is exactly equivalent to `g_print`. If `self` is remote then this is equivalent to calling `g_print` in the invoking process. ## `format` a printf-style format string Formats a message and prints it using the stderr print handler in the invoking process. If `self` is a local invocation then this is exactly equivalent to `g_printerr`. If `self` is remote then this is equivalent to calling `g_printerr` in the invoking process. ## `format` a printf-style format string Sets the exit status that will be used when the invoking process exits. The return value of the `Application::command-line` signal is passed to this function when the handler returns. This is the usual way of setting the exit status. In the event that you want the remote invocation to continue running and want to decide on the exit status in the future, you can use this call. For the case of a remote invocation, the remote process will typically exit when the last reference is dropped on `self`. The exit status of the remote process will be equal to the last value that was set with this function. In the case that the commandline invocation is local, the situation is slightly more complicated. If the commandline invocation results in the mainloop running (ie: because the use-count of the application increased to a non-zero value) then the application is considered to have been 'successful' in a certain sense, and the exit status is always zero. If the application use count is zero, though, the exit status of the local `ApplicationCommandLine` is used. ## `exit_status` the exit status Buffered input stream implements `FilterInputStream` and provides for buffered reads. By default, `BufferedInputStream`'s buffer size is set at 4 kilobytes. To create a buffered input stream, use `BufferedInputStream::new`, or `BufferedInputStream::new_sized` to specify the buffer's size at construction. To get the size of a buffer within a buffered input stream, use `BufferedInputStreamExt::get_buffer_size`. To change the size of a buffered input stream's buffer, use `BufferedInputStreamExt::set_buffer_size`. Note that the buffer's size cannot be reduced below the size of the data within the buffer. # Implements [`BufferedInputStreamExt`](trait.BufferedInputStreamExt.html), [`FilterInputStreamExt`](trait.FilterInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `BufferedInputStream` methods. # Implementors [`BufferedInputStream`](struct.BufferedInputStream.html), [`DataInputStream`](struct.DataInputStream.html) Creates a new `InputStream` from the given `base_stream`, with a buffer set to the default size (4 kilobytes). ## `base_stream` a `InputStream` # Returns a `InputStream` for the given `base_stream`. Creates a new `BufferedInputStream` from the given `base_stream`, with a buffer set to `size`. ## `base_stream` a `InputStream` ## `size` a `gsize` # Returns a `InputStream`. Tries to read `count` bytes from the stream into the buffer. Will block during this read. If `count` is zero, returns zero and does nothing. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if `count` is zero), but never otherwise. If `count` is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and `error` is set accordingly. For the asynchronous, non-blocking, version of this function, see `BufferedInputStreamExt::fill_async`. ## `count` the number of bytes that will be read from the stream ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns the number of bytes read into `self`'s buffer, up to `count`, or -1 on error. Reads data into `self`'s buffer asynchronously, up to `count` size. `io_priority` can be used to prioritize reads. For the synchronous version of this function, see `BufferedInputStreamExt::fill`. If `count` is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. ## `count` the number of bytes that will be read from the stream ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object ## `callback` a `GAsyncReadyCallback` ## `user_data` a `gpointer` Finishes an asynchronous read. ## `result` a `AsyncResult` # Returns a `gssize` of the read stream, or `-1` on an error. Gets the size of the available data within the stream. # Returns size of the available stream. Gets the size of the input buffer. # Returns the current buffer size. Peeks in the buffer, copying data of size `count` into `buffer`, offset `offset` bytes. ## `buffer` a pointer to an allocated chunk of memory ## `offset` a `gsize` ## `count` a `gsize` # Returns a `gsize` of the number of bytes peeked, or -1 on error. Returns the buffer with the currently available bytes. The returned buffer must not be modified and will become invalid when reading from the stream or filling the buffer. ## `count` a `gsize` to get the number of bytes available in the buffer # Returns read-only buffer Tries to read a single byte from the stream or the buffer. Will block during this read. On success, the byte read from the stream is returned. On end of stream -1 is returned but it's not an exceptional error and `error` is not set. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and `error` is set accordingly. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns the byte read from the `self`, or -1 on end of stream or error. Sets the size of the internal buffer of `self` to `size`, or to the size of the contents of the buffer. The buffer can never be resized smaller than its current contents. ## `size` a `gsize` Buffered output stream implements `FilterOutputStream` and provides for buffered writes. By default, `BufferedOutputStream`'s buffer size is set at 4 kilobytes. To create a buffered output stream, use `BufferedOutputStream::new`, or `BufferedOutputStream::new_sized` to specify the buffer's size at construction. To get the size of a buffer within a buffered input stream, use `BufferedOutputStreamExt::get_buffer_size`. To change the size of a buffered output stream's buffer, use `BufferedOutputStreamExt::set_buffer_size`. Note that the buffer's size cannot be reduced below the size of the data within the buffer. # Implements [`BufferedOutputStreamExt`](trait.BufferedOutputStreamExt.html), [`FilterOutputStreamExt`](trait.FilterOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `BufferedOutputStream` methods. # Implementors [`BufferedOutputStream`](struct.BufferedOutputStream.html) Creates a new buffered output stream for a base stream. ## `base_stream` a `OutputStream`. # Returns a `OutputStream` for the given `base_stream`. Creates a new buffered output stream with a given buffer size. ## `base_stream` a `OutputStream`. ## `size` a `gsize`. # Returns a `OutputStream` with an internal buffer set to `size`. Checks if the buffer automatically grows as data is added. # Returns `true` if the `self`'s buffer automatically grows, `false` otherwise. Gets the size of the buffer in the `self`. # Returns the current size of the buffer. Sets whether or not the `self`'s buffer should automatically grow. If `auto_grow` is true, then each write will just make the buffer larger, and you must manually flush the buffer to actually write out the data to the underlying stream. ## `auto_grow` a `gboolean`. Sets the size of the internal buffer to `size`. ## `size` a `gsize`. `BytesIcon` specifies an image held in memory in a common format (usually png) to be used as icon. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IconExt`](trait.IconExt.html), [`LoadableIconExt`](trait.LoadableIconExt.html) Creates a new icon for a bytes. ## `bytes` a `glib::Bytes`. # Returns a `Icon` for the given `bytes`, or `None` on error. Gets the `glib::Bytes` associated with the given `self`. # Returns a `glib::Bytes`, or `None`. The bytes containing the icon. The bytes containing the icon. GCancellable is a thread-safe operation cancellation stack used throughout GIO to allow for cancellation of synchronous and asynchronous operations. # Implements [`CancellableExt`](trait.CancellableExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Cancellable` methods. # Implementors [`Cancellable`](struct.Cancellable.html) Creates a new `Cancellable` object. Applications that want to start one or more operations that should be cancellable should create a `Cancellable` and pass it to the operations. One `Cancellable` can be used in multiple consecutive operations or in multiple concurrent operations. # Returns a `Cancellable`. Gets the top cancellable from the stack. # Returns a `Cancellable` from the top of the stack, or `None` if the stack is empty. Will set `self` to cancelled, and will emit the `Cancellable::cancelled` signal. (However, see the warning about race conditions in the documentation for that signal if you are planning to connect to it.) This function is thread-safe. In other words, you can safely call it from a thread other than the one running the operation that was passed the `self`. If `self` is `None`, this function returns immediately for convenience. The convention within GIO is that cancelling an asynchronous operation causes it to complete asynchronously. That is, if you cancel the operation from the same thread in which it is running, then the operation's `GAsyncReadyCallback` will not be invoked until the application returns to the main loop. Convenience function to connect to the `Cancellable::cancelled` signal. Also handles the race condition that may happen if the cancellable is cancelled right before connecting. `callback` is called at most once, either directly at the time of the connect if `self` is already cancelled, or when `self` is cancelled in some thread. `data_destroy_func` will be called when the handler is disconnected, or immediately if the cancellable is already cancelled. See `Cancellable::cancelled` for details on how to use this. Since GLib 2.40, the lock protecting `self` is not held when `callback` is invoked. This lifts a restriction in place for earlier GLib versions which now makes it easier to write cleanup code that unconditionally invokes e.g. `CancellableExt::cancel`. ## `callback` The `GCallback` to connect. ## `data` Data to pass to `callback`. ## `data_destroy_func` Free function for `data` or `None`. # Returns The id of the signal handler or 0 if `self` has already been cancelled. Disconnects a handler from a cancellable instance similar to `g_signal_handler_disconnect`. Additionally, in the event that a signal handler is currently running, this call will block until the handler has finished. Calling this function from a `Cancellable::cancelled` signal handler will therefore result in a deadlock. This avoids a race condition where a thread cancels at the same time as the cancellable operation is finished and the signal handler is removed. See `Cancellable::cancelled` for details on how to use this. If `self` is `None` or `handler_id` is `0` this function does nothing. ## `handler_id` Handler id of the handler to be disconnected, or `0`. Gets the file descriptor for a cancellable job. This can be used to implement cancellable operations on Unix systems. The returned fd will turn readable when `self` is cancelled. You are not supposed to read from the fd yourself, just check for readable status. Reading to unset the readable status is done with `Cancellable::reset`. After a successful return from this function, you should use `CancellableExt::release_fd` to free up resources allocated for the returned file descriptor. See also `CancellableExt::make_pollfd`. # Returns A valid file descriptor. %-1 if the file descriptor is not supported, or on errors. Checks if a cancellable job has been cancelled. # Returns `true` if `self` is cancelled, FALSE if called with `None` or if item is not cancelled. Creates a `glib::PollFD` corresponding to `self`; this can be passed to `g_poll` and used to poll for cancellation. This is useful both for unix systems without a native poll and for portability to windows. When this function returns `true`, you should use `CancellableExt::release_fd` to free up resources allocated for the `pollfd`. After a `false` return, do not call `CancellableExt::release_fd`. If this function returns `false`, either no `self` was given or resource limits prevent this function from allocating the necessary structures for polling. (On Linux, you will likely have reached the maximum number of file descriptors.) The suggested way to handle these cases is to ignore the `self`. You are not supposed to read from the fd yourself, just check for readable status. Reading to unset the readable status is done with `Cancellable::reset`. ## `pollfd` a pointer to a `glib::PollFD` # Returns `true` if `pollfd` was successfully initialized, `false` on failure to prepare the cancellable. Pops `self` off the cancellable stack (verifying that `self` is on the top of the stack). Pushes `self` onto the cancellable stack. The current cancellable can then be received using `Cancellable::get_current`. This is useful when implementing cancellable operations in code that does not allow you to pass down the cancellable object. This is typically called automatically by e.g. `File` operations, so you rarely have to call this yourself. Releases a resources previously allocated by `CancellableExt::get_fd` or `CancellableExt::make_pollfd`. For compatibility reasons with older releases, calling this function is not strictly required, the resources will be automatically freed when the `self` is finalized. However, the `self` will block scarce file descriptors until it is finalized if this function is not called. This can cause the application to run out of file descriptors when many `GCancellables` are used at the same time. Resets `self` to its uncancelled state. If cancellable is currently in use by any cancellable operation then the behavior of this function is undefined. Note that it is generally not a good idea to reuse an existing cancellable for more operations after it has been cancelled once, as this function might tempt you to do. The recommended practice is to drop the reference to a cancellable after cancelling it, and let it die with the outstanding async operations. You should create a fresh cancellable for further async operations. If the `self` is cancelled, sets the error to notify that the operation was cancelled. # Returns `true` if `self` was cancelled, `false` if it was not Creates a source that triggers if `self` is cancelled and calls its callback of type `GCancellableSourceFunc`. This is primarily useful for attaching to another (non-cancellable) source with `glib::Source::add_child_source` to add cancellability to it. For convenience, you can call this with a `None` `Cancellable`, in which case the source will never trigger. The new `glib::Source` will hold a reference to the `Cancellable`. # Returns the new `glib::Source`. Emitted when the operation has been cancelled. Can be used by implementations of cancellable operations. If the operation is cancelled from another thread, the signal will be emitted in the thread that cancelled the operation, not the thread that is running the operation. Note that disconnecting from this signal (or any signal) in a multi-threaded program is prone to race conditions. For instance it is possible that a signal handler may be invoked even after a call to `g_signal_handler_disconnect` for that handler has already returned. There is also a problem when cancellation happens right before connecting to the signal. If this happens the signal will unexpectedly not be emitted, and checking before connecting to the signal leaves a race condition where this is still happening. In order to make it safe and easy to connect handlers there are two helper functions: `CancellableExt::connect` and `CancellableExt::disconnect` which protect against problems like this. An example of how to us this: ```C // Make sure we don't do unnecessary work if already cancelled if (g_cancellable_set_error_if_cancelled (cancellable, error)) return; // Set up all the data needed to be able to handle cancellation // of the operation my_data = my_data_new (...); id = 0; if (cancellable) id = g_cancellable_connect (cancellable, G_CALLBACK (cancelled_handler) data, NULL); // cancellable operation here... g_cancellable_disconnect (cancellable, id); // cancelled_handler is never called after this, it is now safe // to free the data my_data_free (my_data); ``` Note that the cancelled signal is emitted in the thread that the user cancelled from, which may be the main thread. So, the cancellable signal should not do something that can block. `CharsetConverter` is an implementation of `Converter` based on GIConv. # Implements [`CharsetConverterExt`](trait.CharsetConverterExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ConverterExt`](trait.ConverterExt.html), [`ConverterExtManual`](prelude/trait.ConverterExtManual.html) Trait containing all `CharsetConverter` methods. # Implementors [`CharsetConverter`](struct.CharsetConverter.html) Creates a new `CharsetConverter`. ## `to_charset` destination charset ## `from_charset` source charset # Returns a new `CharsetConverter` or `None` on error. Gets the number of fallbacks that `self` has applied so far. # Returns the number of fallbacks that `self` has applied Gets the `CharsetConverter:use-fallback` property. # Returns `true` if fallbacks are used by `self` Sets the `CharsetConverter:use-fallback` property. ## `use_fallback` `true` to use fallbacks `Converter` is implemented by objects that convert binary data in various ways. The conversion can be stateful and may fail at any place. Some example conversions are: character set conversion, compression, decompression and regular expression replace. # Implements [`ConverterExt`](trait.ConverterExt.html), [`ConverterExtManual`](prelude/trait.ConverterExtManual.html) Trait containing all `Converter` methods. # Implementors [`CharsetConverter`](struct.CharsetConverter.html), [`Converter`](struct.Converter.html), [`ZlibCompressor`](struct.ZlibCompressor.html), [`ZlibDecompressor`](struct.ZlibDecompressor.html) This is the main operation used when converting data. It is to be called multiple times in a loop, and each time it will do some work, i.e. producing some output (in `outbuf`) or consuming some input (from `inbuf`) or both. If its not possible to do any work an error is returned. Note that a single call may not consume all input (or any input at all). Also a call may produce output even if given no input, due to state stored in the converter producing output. If any data was either produced or consumed, and then an error happens, then only the successful conversion is reported and the error is returned on the next call. A full conversion loop involves calling this method repeatedly, each time giving it new input and space output space. When there is no more input data after the data in `inbuf`, the flag `ConverterFlags::InputAtEnd` must be set. The loop will be (unless some error happens) returning `ConverterResult::Converted` each time until all data is consumed and all output is produced, then `ConverterResult::Finished` is returned instead. Note, that `ConverterResult::Finished` may be returned even if `ConverterFlags::InputAtEnd` is not set, for instance in a decompression converter where the end of data is detectable from the data (and there might even be other data after the end of the compressed data). When some data has successfully been converted `bytes_read` and is set to the number of bytes read from `inbuf`, and `bytes_written` is set to indicate how many bytes was written to `outbuf`. If there are more data to output or consume (i.e. unless the `ConverterFlags::InputAtEnd` is specified) then `ConverterResult::Converted` is returned, and if no more data is to be output then `ConverterResult::Finished` is returned. On error `ConverterResult::Error` is returned and `error` is set accordingly. Some errors need special handling: `IOErrorEnum::NoSpace` is returned if there is not enough space to write the resulting converted data, the application should call the function again with a larger `outbuf` to continue. `IOErrorEnum::PartialInput` is returned if there is not enough input to fully determine what the conversion should produce, and the `ConverterFlags::InputAtEnd` flag is not set. This happens for example with an incomplete multibyte sequence when converting text, or when a regexp matches up to the end of the input (and may match further input). It may also happen when `inbuf_size` is zero and there is no more data to produce. When this happens the application should read more input and then call the function again. If further input shows that there is no more data call the function again with the same data but with the `ConverterFlags::InputAtEnd` flag set. This may cause the conversion to finish as e.g. in the regexp match case (or, to fail again with `IOErrorEnum::PartialInput` in e.g. a charset conversion where the input is actually partial). After `Converter::convert` has returned `ConverterResult::Finished` the converter object is in an invalid state where its not allowed to call `Converter::convert` anymore. At this time you can only free the object or call `Converter::reset` to reset it to the initial state. If the flag `ConverterFlags::Flush` is set then conversion is modified to try to write out all internal state to the output. The application has to call the function multiple times with the flag set, and when the available input has been consumed and all internal state has been produced then `ConverterResult::Flushed` (or `ConverterResult::Finished` if really at the end) is returned instead of `ConverterResult::Converted`. This is somewhat similar to what happens at the end of the input stream, but done in the middle of the data. This has different meanings for different conversions. For instance in a compression converter it would mean that we flush all the compression state into output such that if you uncompress the compressed data you get back all the input data. Doing this may make the final file larger due to padding though. Another example is a regexp conversion, where if you at the end of the flushed data have a match, but there is also a potential longer match. In the non-flushed case we would ask for more input, but when flushing we treat this as the end of input and do the match. Flushing is not always possible (like if a charset converter flushes at a partial multibyte sequence). Converters are supposed to try to produce as much output as possible and then return an error (typically `IOErrorEnum::PartialInput`). ## `inbuf` the buffer containing the data to convert. ## `inbuf_size` the number of bytes in `inbuf` ## `outbuf` a buffer to write converted data in. ## `outbuf_size` the number of bytes in `outbuf`, must be at least one ## `flags` a `ConverterFlags` controlling the conversion details ## `bytes_read` will be set to the number of bytes read from `inbuf` on success ## `bytes_written` will be set to the number of bytes written to `outbuf` on success # Returns a `ConverterResult`, `ConverterResult::Error` on error. Resets all internal state in the converter, making it behave as if it was just created. If the converter has any internal state that would produce output then that output is lost. Converter input stream implements `InputStream` and allows conversion of data of various types during reading. As of GLib 2.34, `ConverterInputStream` implements `PollableInputStream`. # Implements [`ConverterInputStreamExt`](trait.ConverterInputStreamExt.html), [`FilterInputStreamExt`](trait.FilterInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableInputStreamExt`](trait.PollableInputStreamExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html), [`PollableInputStreamExtManual`](prelude/trait.PollableInputStreamExtManual.html) Trait containing all `ConverterInputStream` methods. # Implementors [`ConverterInputStream`](struct.ConverterInputStream.html) Creates a new converter input stream for the `base_stream`. ## `base_stream` a `InputStream` ## `converter` a `Converter` # Returns a new `InputStream`. Gets the `Converter` that is used by `self`. # Returns the converter of the converter input stream Converter output stream implements `OutputStream` and allows conversion of data of various types during reading. As of GLib 2.34, `ConverterOutputStream` implements `PollableOutputStream`. # Implements [`ConverterOutputStreamExt`](trait.ConverterOutputStreamExt.html), [`FilterOutputStreamExt`](trait.FilterOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableOutputStreamExt`](trait.PollableOutputStreamExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html), [`PollableOutputStreamExtManual`](prelude/trait.PollableOutputStreamExtManual.html) Trait containing all `ConverterOutputStream` methods. # Implementors [`ConverterOutputStream`](struct.ConverterOutputStream.html) Creates a new converter output stream for the `base_stream`. ## `base_stream` a `OutputStream` ## `converter` a `Converter` # Returns a new `OutputStream`. Gets the `Converter` that is used by `self`. # Returns the converter of the converter output stream Results returned from `Converter::convert`. There was an error during conversion. Some data was consumed or produced The conversion is finished Flushing is finished The `Credentials` type is a reference-counted wrapper for native credentials. This information is typically used for identifying, authenticating and authorizing other processes. Some operating systems supports looking up the credentials of the remote peer of a communication endpoint - see e.g. `SocketExt::get_credentials`. Some operating systems supports securely sending and receiving credentials over a Unix Domain Socket, see `UnixCredentialsMessage`, `UnixConnection::send_credentials` and `UnixConnection::receive_credentials` for details. On Linux, the native credential type is a struct ucred - see the unix(7) man page for details. This corresponds to `CredentialsType::LinuxUcred`. On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native credential type is a struct cmsgcred. This corresponds to `CredentialsType::FreebsdCmsgcred`. On NetBSD, the native credential type is a struct unpcbid. This corresponds to `CredentialsType::NetbsdUnpcbid`. On OpenBSD, the native credential type is a struct sockpeercred. This corresponds to `CredentialsType::OpenbsdSockpeercred`. On Solaris (including OpenSolaris and its derivatives), the native credential type is a ucred_t. This corresponds to `CredentialsType::SolarisUcred`. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Credentials` object with credentials matching the the current process. # Returns A `Credentials`. Free with `gobject::ObjectExt::unref`. Gets a pointer to native credentials of type `native_type` from `self`. It is a programming error (which will cause an warning to be logged) to use this method if there is no `Credentials` support for the OS or if `native_type` isn't supported by the OS. ## `native_type` The type of native credentials to get. # Returns The pointer to native credentials or `None` if the operation there is no `Credentials` support for the OS or if `native_type` isn't supported by the OS. Do not free the returned data, it is owned by `self`. Tries to get the UNIX process identifier from `self`. This method is only available on UNIX platforms. This operation can fail if `Credentials` is not supported on the OS or if the native credentials type does not contain information about the UNIX process ID. # Returns The UNIX process ID, or -1 if `error` is set. Tries to get the UNIX user identifier from `self`. This method is only available on UNIX platforms. This operation can fail if `Credentials` is not supported on the OS or if the native credentials type does not contain information about the UNIX user. # Returns The UNIX user identifier or -1 if `error` is set. Checks if `self` and `other_credentials` is the same user. This operation can fail if `Credentials` is not supported on the the OS. ## `other_credentials` A `Credentials`. # Returns `true` if `self` and `other_credentials` has the same user, `false` otherwise or if `error` is set. Copies the native credentials of type `native_type` from `native` into `self`. It is a programming error (which will cause an warning to be logged) to use this method if there is no `Credentials` support for the OS or if `native_type` isn't supported by the OS. ## `native_type` The type of native credentials to set. ## `native` A pointer to native credentials. Tries to set the UNIX user identifier on `self`. This method is only available on UNIX platforms. This operation can fail if `Credentials` is not supported on the OS or if the native credentials type does not contain information about the UNIX user. It can also fail if the OS does not allow the use of "spoofed" credentials. ## `uid` The UNIX user identifier to set. # Returns `true` if `uid` was set, `false` if error is set. Creates a human-readable textual representation of `self` that can be used in logging and debug messages. The format of the returned string may change in future GLib release. # Returns A string that should be freed with `g_free`. Enumeration describing different kinds of native credential types. Indicates an invalid native credential type. The native credentials type is a struct ucred. The native credentials type is a struct cmsgcred. The native credentials type is a struct sockpeercred. Added in 2.30. The native credentials type is a ucred_t. Added in 2.40. The native credentials type is a struct unpcbid. Data input stream implements `InputStream` and includes functions for reading structured data directly from a binary input stream. # Implements [`DataInputStreamExt`](trait.DataInputStreamExt.html), [`BufferedInputStreamExt`](trait.BufferedInputStreamExt.html), [`FilterInputStreamExt`](trait.FilterInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `DataInputStream` methods. # Implementors [`DataInputStream`](struct.DataInputStream.html) Creates a new data input stream for the `base_stream`. ## `base_stream` a `InputStream`. # Returns a new `DataInputStream`. Gets the byte order for the data input stream. # Returns the `self`'s current `DataStreamByteOrder`. Gets the current newline type for the `self`. # Returns `DataStreamNewlineType` for the given `self`. Reads an unsigned 8-bit/1-byte value from `self`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns an unsigned 8-bit/1-byte value read from the `self` or `0` if an error occurred. Reads a 16-bit/2-byte value from `self`. In order to get the correct byte order for this read operation, see `DataInputStreamExt::get_byte_order` and `DataInputStreamExt::set_byte_order`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a signed 16-bit/2-byte value read from `self` or `0` if an error occurred. Reads a signed 32-bit/4-byte value from `self`. In order to get the correct byte order for this read operation, see `DataInputStreamExt::get_byte_order` and `DataInputStreamExt::set_byte_order`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a signed 32-bit/4-byte value read from the `self` or `0` if an error occurred. Reads a 64-bit/8-byte value from `self`. In order to get the correct byte order for this read operation, see `DataInputStreamExt::get_byte_order` and `DataInputStreamExt::set_byte_order`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a signed 64-bit/8-byte value read from `self` or `0` if an error occurred. Reads a line from the data input stream. Note that no encoding checks or conversion is performed; the input is not guaranteed to be UTF-8, and may in fact have embedded NUL characters. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `length` a `gsize` to get the length of the data read in. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a NUL terminated byte array with the line that was read in (without the newlines). Set `length` to a `gsize` to get the length of the read line. On an error, it will return `None` and `error` will be set. If there's no content to read, it will still return `None`, but `error` won't be set. The asynchronous version of `DataInputStream::read_line`. It is an error to have two outstanding calls to this function. When the operation is finished, `callback` will be called. You can then call `DataInputStreamExt::read_line_finish` to get the result of the operation. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied. ## `user_data` the data to pass to callback function. Finish an asynchronous call started by `DataInputStream::read_line_async`. Note the warning about string encoding in `DataInputStream::read_line` applies here as well. ## `result` the `AsyncResult` that was provided to the callback. ## `length` a `gsize` to get the length of the data read in. # Returns a NUL-terminated byte array with the line that was read in (without the newlines). Set `length` to a `gsize` to get the length of the read line. On an error, it will return `None` and `error` will be set. If there's no content to read, it will still return `None`, but `error` won't be set. Finish an asynchronous call started by `DataInputStream::read_line_async`. ## `result` the `AsyncResult` that was provided to the callback. ## `length` a `gsize` to get the length of the data read in. # Returns a string with the line that was read in (without the newlines). Set `length` to a `gsize` to get the length of the read line. On an error, it will return `None` and `error` will be set. For UTF-8 conversion errors, the set error domain is `G_CONVERT_ERROR`. If there's no content to read, it will still return `None`, but `error` won't be set. Reads a UTF-8 encoded line from the data input stream. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `length` a `gsize` to get the length of the data read in. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set `length` to a `gsize` to get the length of the read line. On an error, it will return `None` and `error` will be set. For UTF-8 conversion errors, the set error domain is `G_CONVERT_ERROR`. If there's no content to read, it will still return `None`, but `error` won't be set. Reads an unsigned 16-bit/2-byte value from `self`. In order to get the correct byte order for this read operation, see `DataInputStreamExt::get_byte_order` and `DataInputStreamExt::set_byte_order`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns an unsigned 16-bit/2-byte value read from the `self` or `0` if an error occurred. Reads an unsigned 32-bit/4-byte value from `self`. In order to get the correct byte order for this read operation, see `DataInputStreamExt::get_byte_order` and `DataInputStreamExt::set_byte_order`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns an unsigned 32-bit/4-byte value read from the `self` or `0` if an error occurred. Reads an unsigned 64-bit/8-byte value from `self`. In order to get the correct byte order for this read operation, see `DataInputStreamExt::get_byte_order`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns an unsigned 64-bit/8-byte read from `self` or `0` if an error occurred. Reads a string from the data input stream, up to the first occurrence of any of the stop characters. Note that, in contrast to `DataInputStreamExt::read_until_async`, this function consumes the stop character that it finds. Don't use this function in new code. Its functionality is inconsistent with `DataInputStreamExt::read_until_async`. Both functions will be marked as deprecated in a future release. Use `DataInputStreamExt::read_upto` instead, but note that that function does not consume the stop character. # Deprecated since 2.56 Use `DataInputStreamExt::read_upto` instead, which has more consistent behaviour regarding the stop character. ## `stop_chars` characters to terminate the read. ## `length` a `gsize` to get the length of the data read in. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a string with the data that was read before encountering any of the stop characters. Set `length` to a `gsize` to get the length of the string. This function will return `None` on an error. The asynchronous version of `DataInputStreamExt::read_until`. It is an error to have two outstanding calls to this function. Note that, in contrast to `DataInputStreamExt::read_until`, this function does not consume the stop character that it finds. You must read it for yourself. When the operation is finished, `callback` will be called. You can then call `DataInputStreamExt::read_until_finish` to get the result of the operation. Don't use this function in new code. Its functionality is inconsistent with `DataInputStreamExt::read_until`. Both functions will be marked as deprecated in a future release. Use `DataInputStreamExt::read_upto_async` instead. # Deprecated since 2.56 Use `DataInputStreamExt::read_upto_async` instead, which has more consistent behaviour regarding the stop character. ## `stop_chars` characters to terminate the read. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied. ## `user_data` the data to pass to callback function. Finish an asynchronous call started by `DataInputStreamExt::read_until_async`. # Deprecated since 2.56 Use `DataInputStreamExt::read_upto_finish` instead, which has more consistent behaviour regarding the stop character. ## `result` the `AsyncResult` that was provided to the callback. ## `length` a `gsize` to get the length of the data read in. # Returns a string with the data that was read before encountering any of the stop characters. Set `length` to a `gsize` to get the length of the string. This function will return `None` on an error. Reads a string from the data input stream, up to the first occurrence of any of the stop characters. In contrast to `DataInputStreamExt::read_until`, this function does not consume the stop character. You have to use `DataInputStreamExt::read_byte` to get it before calling `DataInputStreamExt::read_upto` again. Note that `stop_chars` may contain '\0' if `stop_chars_len` is specified. The returned string will always be nul-terminated on success. ## `stop_chars` characters to terminate the read ## `stop_chars_len` length of `stop_chars`. May be -1 if `stop_chars` is nul-terminated ## `length` a `gsize` to get the length of the data read in ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a string with the data that was read before encountering any of the stop characters. Set `length` to a `gsize` to get the length of the string. This function will return `None` on an error The asynchronous version of `DataInputStreamExt::read_upto`. It is an error to have two outstanding calls to this function. In contrast to `DataInputStreamExt::read_until`, this function does not consume the stop character. You have to use `DataInputStreamExt::read_byte` to get it before calling `DataInputStreamExt::read_upto` again. Note that `stop_chars` may contain '\0' if `stop_chars_len` is specified. When the operation is finished, `callback` will be called. You can then call `DataInputStreamExt::read_upto_finish` to get the result of the operation. ## `stop_chars` characters to terminate the read ## `stop_chars_len` length of `stop_chars`. May be -1 if `stop_chars` is nul-terminated ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finish an asynchronous call started by `DataInputStreamExt::read_upto_async`. Note that this function does not consume the stop character. You have to use `DataInputStreamExt::read_byte` to get it before calling `DataInputStreamExt::read_upto_async` again. The returned string will always be nul-terminated on success. ## `result` the `AsyncResult` that was provided to the callback ## `length` a `gsize` to get the length of the data read in # Returns a string with the data that was read before encountering any of the stop characters. Set `length` to a `gsize` to get the length of the string. This function will return `None` on an error. This function sets the byte order for the given `self`. All subsequent reads from the `self` will be read in the given `order`. ## `order` a `DataStreamByteOrder` to set. Sets the newline type for the `self`. Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read chunk ends in "CR" we must read an additional byte to know if this is "CR" or "CR LF", and this might block if there is no more data available. ## `type_` the type of new line return as `DataStreamNewlineType`. Data output stream implements `OutputStream` and includes functions for writing data directly to an output stream. # Implements [`DataOutputStreamExt`](trait.DataOutputStreamExt.html), [`FilterOutputStreamExt`](trait.FilterOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `DataOutputStream` methods. # Implementors [`DataOutputStream`](struct.DataOutputStream.html) Creates a new data output stream for `base_stream`. ## `base_stream` a `OutputStream`. # Returns `DataOutputStream`. Gets the byte order for the stream. # Returns the `DataStreamByteOrder` for the `self`. Puts a byte into the output stream. ## `data` a `guchar`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if `data` was successfully added to the `self`. Puts a signed 16-bit integer into the output stream. ## `data` a `gint16`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if `data` was successfully added to the `self`. Puts a signed 32-bit integer into the output stream. ## `data` a `gint32`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if `data` was successfully added to the `self`. Puts a signed 64-bit integer into the stream. ## `data` a `gint64`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if `data` was successfully added to the `self`. Puts a string into the output stream. ## `str` a string. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if `string` was successfully added to the `self`. Puts an unsigned 16-bit integer into the output stream. ## `data` a `guint16`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if `data` was successfully added to the `self`. Puts an unsigned 32-bit integer into the stream. ## `data` a `guint32`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if `data` was successfully added to the `self`. Puts an unsigned 64-bit integer into the stream. ## `data` a `guint64`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if `data` was successfully added to the `self`. Sets the byte order of the data output stream to `order`. ## `order` a `DataStreamByteOrder`. Determines the byte ordering that is used when writing multi-byte entities (such as integers) to the stream. Determines the byte ordering that is used when writing multi-byte entities (such as integers) to the stream. `DataStreamByteOrder` is used to ensure proper endianness of streaming data sources across various machine architectures. Selects Big Endian byte order. Selects Little Endian byte order. Selects endianness based on host machine's architecture. `DataStreamNewlineType` is used when checking for or setting the line endings for a given file. Selects "LF" line endings, common on most modern UNIX platforms. Selects "CR" line endings. Selects "CR, LF" line ending, common on Microsoft Windows. Automatically try to handle any line ending type. `DesktopAppInfo` is an implementation of `AppInfo` based on desktop files. Note that `` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file when using it. # Implements [`DesktopAppInfoExt`](trait.DesktopAppInfoExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AppInfoExt`](trait.AppInfoExt.html) Trait containing all `DesktopAppInfo` methods. # Implementors [`DesktopAppInfo`](struct.DesktopAppInfo.html) Creates a new `DesktopAppInfo` based on a desktop file id. A desktop file id is the basename of the desktop file, including the .desktop extension. GIO is looking for a desktop file with this name in the `applications` subdirectories of the XDG data directories (i.e. the directories specified in the `XDG_DATA_HOME` and `XDG_DATA_DIRS` environment variables). GIO also supports the prefix-to-subdirectory mapping that is described in the [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) (i.e. a desktop id of kde-foo.desktop will match `/usr/share/applications/kde/foo.desktop`). ## `desktop_id` the desktop file id # Returns a new `DesktopAppInfo`, or `None` if no desktop file with that id exists. Creates a new `DesktopAppInfo`. ## `filename` the path of a desktop file, in the GLib filename encoding # Returns a new `DesktopAppInfo` or `None` on error. Creates a new `DesktopAppInfo`. ## `key_file` an opened `glib::KeyFile` # Returns a new `DesktopAppInfo` or `None` on error. Gets all applications that implement `interface`. An application implements an interface if that interface is listed in the Implements= line of the desktop file of the application. ## `interface` the name of the interface # Returns a list of `DesktopAppInfo` objects. Searches desktop files for ones that match `search_string`. The return value is an array of strvs. Each strv contains a list of applications that matched `search_string` with an equal score. The outer list is sorted by score so that the first strv contains the best-matching applications, and so on. The algorithm for determining matches is undefined and may change at any time. ## `search_string` the search string to use # Returns a list of strvs. Free each item with `g_strfreev` and free the outer list with `g_free`. Gets the user-visible display name of the "additional application action" specified by `action_name`. This corresponds to the "Name" key within the keyfile group for the action. ## `action_name` the name of the action as from `DesktopAppInfoExt::list_actions` # Returns the locale-specific action name Looks up a boolean value in the keyfile backing `self`. The `key` is looked up in the "Desktop Entry" group. ## `key` the key to look up # Returns the boolean value, or `false` if the key is not found Gets the categories from the desktop file. # Returns The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it. When `self` was created from a known filename, return it. In some situations such as the `DesktopAppInfo` returned from `DesktopAppInfo::new_from_keyfile`, this function will return `None`. # Returns The full path to the file for `self`, or `None` if not known. Gets the generic name from the destkop file. # Returns The value of the GenericName key A desktop file is hidden if the Hidden key in it is set to True. # Returns `true` if hidden, `false` otherwise. Gets the keywords from the desktop file. # Returns The value of the Keywords key Looks up a localized string value in the keyfile backing `self` translated to the current locale. The `key` is looked up in the "Desktop Entry" group. Feature: `v2_56` ## `key` the key to look up # Returns a newly allocated string, or `None` if the key is not found Gets the value of the NoDisplay key, which helps determine if the application info should be shown in menus. See `G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and `AppInfo::should_show`. # Returns The value of the NoDisplay key Checks if the application info should be shown in menus that list available applications for a specific name of the desktop, based on the `OnlyShowIn` and `NotShowIn` keys. `desktop_env` should typically be given as `None`, in which case the `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want to override the default mechanism then you may specify `desktop_env`, but this is not recommended. Note that `AppInfo::should_show` for `self` will include this check (with `None` for `desktop_env`) as well as additional checks. ## `desktop_env` a string specifying a desktop name # Returns `true` if the `self` should be shown in `desktop_env` according to the `OnlyShowIn` and `NotShowIn` keys, `false` otherwise. Retrieves the StartupWMClass field from `self`. This represents the WM_CLASS property of the main window of the application, if launched through `self`. # Returns the startup WM class, or `None` if none is set in the desktop file. Looks up a string value in the keyfile backing `self`. The `key` is looked up in the "Desktop Entry" group. ## `key` the key to look up # Returns a newly allocated string, or `None` if the key is not found Returns whether `key` exists in the "Desktop Entry" group of the keyfile backing `self`. ## `key` the key to look up # Returns `true` if the `key` exists Activates the named application action. You may only call this function on action names that were returned from `DesktopAppInfoExt::list_actions`. Note that if the main entry of the desktop file indicates that the application supports startup notification, and `launch_context` is non-`None`, then startup notification will be used when activating the action (and as such, invocation of the action on the receiving side must signal the end of startup notification when it is completed). This is the expected behaviour of applications declaring additional actions, as per the desktop file specification. As with `AppInfo::launch` there is no way to detect failures that occur while using this function. ## `action_name` the name of the action as from `DesktopAppInfoExt::list_actions` ## `launch_context` a `AppLaunchContext` This function performs the equivalent of `AppInfo::launch_uris`, but is intended primarily for operating system components that launch applications. Ordinary applications should use `AppInfo::launch_uris`. If the application is launched via GSpawn, then `spawn_flags`, `user_setup` and `user_setup_data` are used for the call to `g_spawn_async`. Additionally, `pid_callback` (with `pid_callback_data`) will be called to inform about the PID of the created process. See `g_spawn_async_with_pipes` for information on certain parameter conditions that can enable an optimized `posix_spawn` codepath to be used. If application launching occurs via some other mechanism (eg: D-Bus activation) then `spawn_flags`, `user_setup`, `user_setup_data`, `pid_callback` and `pid_callback_data` are ignored. ## `uris` List of URIs ## `launch_context` a `AppLaunchContext` ## `spawn_flags` `glib::SpawnFlags`, used for each process ## `user_setup` a `GSpawnChildSetupFunc`, used once for each process. ## `user_setup_data` User data for `user_setup` ## `pid_callback` Callback for child processes ## `pid_callback_data` User data for `callback` # Returns `true` on successful launch, `false` otherwise. Equivalent to `DesktopAppInfoExt::launch_uris_as_manager` but allows you to pass in file descriptors for the stdin, stdout and stderr streams of the launched process. If application launching occurs via some non-spawn mechanism (e.g. D-Bus activation) then `stdin_fd`, `stdout_fd` and `stderr_fd` are ignored. Feature: `v2_58` ## `uris` List of URIs ## `launch_context` a `AppLaunchContext` ## `spawn_flags` `glib::SpawnFlags`, used for each process ## `user_setup` a `GSpawnChildSetupFunc`, used once for each process. ## `user_setup_data` User data for `user_setup` ## `pid_callback` Callback for child processes ## `pid_callback_data` User data for `callback` ## `stdin_fd` file descriptor to use for child's stdin, or -1 ## `stdout_fd` file descriptor to use for child's stdout, or -1 ## `stderr_fd` file descriptor to use for child's stderr, or -1 # Returns `true` on successful launch, `false` otherwise. Returns the list of "additional application actions" supported on the desktop file, as per the desktop file specification. As per the specification, this is the list of actions that are explicitly listed in the "Actions" key of the [Desktop Entry] group. # Returns a list of strings, always non-`None` The origin filename of this `DesktopAppInfo` The origin filename of this `DesktopAppInfo` `Drive` - this represent a piece of hardware connected to the machine. It's generally only created for removable hardware or hardware with removable media. `Drive` is a container class for `Volume` objects that stem from the same piece of media. As such, `Drive` abstracts a drive with (or without) removable media and provides operations for querying whether media is available, determining whether media change is automatically detected and ejecting the media. If the `Drive` reports that media isn't automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potententially expensive and may spin up the drive creating noise. `Drive` supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual semantics and side-effects of starting/stopping a `Drive` may vary according to implementation. To choose the correct verbs in e.g. a file manager, use `Drive::get_start_stop_type`. For porting from GnomeVFS note that there is no equivalent of `Drive` in that API. # Implements [`DriveExt`](trait.DriveExt.html) Trait containing all `Drive` methods. # Implementors [`Drive`](struct.Drive.html) Checks if a drive can be ejected. # Returns `true` if the `self` can be ejected, `false` otherwise. Checks if a drive can be polled for media changes. # Returns `true` if the `self` can be polled for media changes, `false` otherwise. Checks if a drive can be started. # Returns `true` if the `self` can be started, `false` otherwise. Checks if a drive can be started degraded. # Returns `true` if the `self` can be started degraded, `false` otherwise. Checks if a drive can be stopped. # Returns `true` if the `self` can be stopped, `false` otherwise. Ejects a drive. This is an asynchronous operation, and is finished by calling `Drive::eject_with_operation_finish` with the `self` and `AsyncResult` data returned in the `callback`. ## `flags` flags affecting the unmount if required for eject ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data passed to `callback`. Finishes ejecting a drive. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. ## `result` a `AsyncResult`. # Returns `true` if the drive was successfully ejected. `false` otherwise. Gets the kinds of identifiers that `self` has. Use `Drive::get_identifier` to obtain the identifiers themselves. # Returns a `None`-terminated array of strings containing kinds of identifiers. Use `g_strfreev` to free. Gets the icon for `self`. # Returns `Icon` for the `self`. Free the returned object with `gobject::ObjectExt::unref`. Gets the identifier of the given kind for `self`. The only identifier currently available is `G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE`. ## `kind` the kind of identifier to return # Returns a newly allocated string containing the requested identifier, or `None` if the `Drive` doesn't have this kind of identifier. Gets the name of `self`. # Returns a string containing `self`'s name. The returned string should be freed when no longer needed. Gets the sort key for `self`, if any. # Returns Sorting key for `self` or `None` if no such key is available. Gets a hint about how a drive can be started/stopped. # Returns A value from the `DriveStartStopType` enumeration. Gets the icon for `self`. # Returns symbolic `Icon` for the `self`. Free the returned object with `gobject::ObjectExt::unref`. Get a list of mountable volumes for `self`. The returned list should be freed with `glib::List::free`, after its elements have been unreffed with `gobject::ObjectExt::unref`. # Returns `glib::List` containing any `Volume` objects on the given `self`. Checks if the `self` has media. Note that the OS may not be polling the drive for media changes; see `Drive::is_media_check_automatic` for more details. # Returns `true` if `self` has media, `false` otherwise. Check if `self` has any mountable volumes. # Returns `true` if the `self` contains volumes, `false` otherwise. Checks if `self` is capabable of automatically detecting media changes. # Returns `true` if the `self` is capabable of automatically detecting media changes, `false` otherwise. Checks if the `self` supports removable media. # Returns `true` if `self` supports removable media, `false` otherwise. Checks if the `Drive` and/or its media is considered removable by the user. See `Drive::is_media_removable`. Feature: `v2_50` # Returns `true` if `self` and/or its media is considered removable, `false` otherwise. Asynchronously polls `self` to see if media has been inserted or removed. When the operation is finished, `callback` will be called. You can then call `Drive::poll_for_media_finish` to obtain the result of the operation. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data to pass to `callback` Finishes an operation started with `Drive::poll_for_media` on a drive. ## `result` a `AsyncResult`. # Returns `true` if the drive has been poll_for_mediaed successfully, `false` otherwise. Asynchronously starts a drive. When the operation is finished, `callback` will be called. You can then call `Drive::start_finish` to obtain the result of the operation. ## `flags` flags affecting the start operation. ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data to pass to `callback` Finishes starting a drive. ## `result` a `AsyncResult`. # Returns `true` if the drive has been started successfully, `false` otherwise. Asynchronously stops a drive. When the operation is finished, `callback` will be called. You can then call `Drive::stop_finish` to obtain the result of the operation. ## `flags` flags affecting the unmount if required for stopping. ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data to pass to `callback` Finishes stopping a drive. ## `result` a `AsyncResult`. # Returns `true` if the drive has been stopped successfully, `false` otherwise. Emitted when the drive's state has changed. This signal is emitted when the `Drive` have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. Emitted when the physical eject button (if any) of a drive has been pressed. Emitted when the physical stop button (if any) of a drive has been pressed. Enumeration describing how a drive can be started/stopped. Unknown or drive doesn't support start/stop. The stop method will physically shut down the drive and e.g. power down the port the drive is attached to. The start/stop methods are used for connecting/disconnect to the drive over the network. The start/stop methods will assemble/disassemble a virtual drive from several physical drives. The start/stop methods will unlock/lock the disk (for example using the ATA ``SECURITY UNLOCK DEVICE`` command) `Emblem` is an implementation of `Icon` that supports having an emblem, which is an icon with additional properties. It can than be added to a `EmblemedIcon`. Currently, only metainformation about the emblem's origin is supported. More may be added in the future. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IconExt`](trait.IconExt.html) Creates a new emblem for `icon`. ## `icon` a GIcon containing the icon. # Returns a new `Emblem`. Creates a new emblem for `icon`. ## `icon` a GIcon containing the icon. ## `origin` a GEmblemOrigin enum defining the emblem's origin # Returns a new `Emblem`. Gives back the icon from `self`. # Returns a `Icon`. The returned object belongs to the emblem and should not be modified or freed. Gets the origin of the emblem. # Returns the origin of the emblem GEmblemOrigin is used to add information about the origin of the emblem to `Emblem`. Emblem of unknown origin Emblem adds device-specific information Emblem depicts live metadata, such as "readonly" Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) `EmblemedIcon` is an implementation of `Icon` that supports adding an emblem to an icon. Adding multiple emblems to an icon is ensured via `EmblemedIconExt::add_emblem`. Note that `EmblemedIcon` allows no control over the position of the emblems. See also `Emblem` for more information. # Implements [`EmblemedIconExt`](trait.EmblemedIconExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IconExt`](trait.IconExt.html) Trait containing all `EmblemedIcon` methods. # Implementors [`EmblemedIcon`](struct.EmblemedIcon.html) Creates a new emblemed icon for `icon` with the emblem `emblem`. ## `icon` a `Icon` ## `emblem` a `Emblem`, or `None` # Returns a new `Icon` Adds `emblem` to the `glib::List` of `GEmblems`. ## `emblem` a `Emblem` Removes all the emblems from `icon`. Gets the list of emblems for the `icon`. # Returns a `glib::List` of `GEmblems` that is owned by `self` Gets the main icon for `self`. # Returns a `Icon` that is owned by `self` `File` is a high level abstraction for manipulating files on a virtual file system. `GFiles` are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that `File` objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations (see `InputStream` and `OutputStream`). To construct a `File`, you can use: - `File::new_for_path` if you have a path. - `File::new_for_uri` if you have a URI. - `File::new_for_commandline_arg` for a command line argument. - `File::new_tmp` to create a temporary file from a template. - `File::parse_name` from a UTF-8 string gotten from `File::get_parse_name`. - `File::new_build_filename` to create a file from path elements. One way to think of a `File` is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as `GFiles` are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem. `GFiles` make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with `File` using `File::get_parent` to get an identifier for the parent directory, `File::get_child` to get a child within a directory, `File::resolve_relative_path` to resolve a relative path between two `GFiles`. There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call `File::get_parent` on two different files. All `GFiles` have a basename (get with `File::get_basename`). These names are byte strings that are used to identify the file on the filesystem (relative to its parent directory) and there is no guarantees that they have any particular charset encoding or even make any sense at all. If you want to use filenames in a user interface you should use the display name that you can get by requesting the `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME` attribute with `File::query_info`. This is guaranteed to be in UTF-8 and can be used in a user interface. But always store the real basename or the `File` to use to actually access the file, because there is no way to go from a display name to the actual name. Using `File` as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, hard or soft links may cause two different `GFiles` to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and long names on FAT/NTFS, or bind mounts in Linux. If you want to check if two `GFiles` point to the same file you can query for the `G_FILE_ATTRIBUTE_ID_FILE` attribute. Note that `File` does some trivial canonicalization of pathnames passed in, so that trivial differences in the path string used at creation (duplicated slashes, slash at end of path, "." or ".." path segments, etc) does not create different `GFiles`. Many `File` operations have both synchronous and asynchronous versions to suit your application. Asynchronous versions of synchronous functions simply have `_async` appended to their function names. The asynchronous I/O functions call a `GAsyncReadyCallback` which is then used to finalize the operation, producing a GAsyncResult which is then passed to the function's matching `_finish` operation. It is highly recommended to use asynchronous calls when running within a shared main loop, such as in the main thread of an application. This avoids I/O operations blocking other sources on the main loop from being dispatched. Synchronous I/O operations should be performed from worker threads. See the [introduction to asynchronous programming section][async-programming] for more. Some `File` operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include: - `File::mount_mountable` to mount a mountable file. - `File::unmount_mountable_with_operation` to unmount a mountable file. - `File::eject_mountable_with_operation` to eject a mountable file. ## Entity Tags # {`gfile`-etag} One notable feature of `GFiles` are entity tags, or "etags" for short. Entity tags are somewhat like a more abstract version of the traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. See the HTTP 1.1 [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) for HTTP Etag headers, which are a very similar concept. # Implements [`FileExt`](trait.FileExt.html), [`FileExtManual`](prelude/trait.FileExtManual.html) Trait containing all `File` methods. # Implementors [`File`](struct.File.html) Constructs a `File` from a series of elements using the correct separator for filenames. Using this function is equivalent to calling `g_build_filename`, followed by `File::new_for_path` on the result. Feature: `v2_56` ## `first_element` the first element in the path # Returns a new `File` Creates a `File` with the given argument from the command line. The value of `arg` can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if `arg` points to a malformed path. Note that on Windows, this function expects its argument to be in UTF-8 -- not the system code page. This means that you should not use this function with string from argv as it is passed to `main`. `g_win32_get_command_line` will return a UTF-8 version of the commandline. `Application` also uses UTF-8 but `ApplicationCommandLineExt::create_file_for_arg` may be more useful for you there. It is also always possible to use this function with `glib::OptionContext` arguments of type `glib::OptionArg::Filename`. ## `arg` a command line string # Returns a new `File`. Free the returned object with `gobject::ObjectExt::unref`. Creates a `File` with the given argument from the command line. This function is similar to `File::new_for_commandline_arg` except that it allows for passing the current working directory as an argument instead of using the current working directory of the process. This is useful if the commandline argument was given in a context other than the invocation of the current process. See also `ApplicationCommandLineExt::create_file_for_arg`. ## `arg` a command line string ## `cwd` the current working directory of the commandline # Returns a new `File` Constructs a `File` for a given path. This operation never fails, but the returned object might not support any I/O operation if `path` is malformed. ## `path` a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. # Returns a new `File` for the given `path`. Free the returned object with `gobject::ObjectExt::unref`. Constructs a `File` for a given URI. This operation never fails, but the returned object might not support any I/O operation if `uri` is malformed or if the uri type is not supported. ## `uri` a UTF-8 string containing a URI # Returns a new `File` for the given `uri`. Free the returned object with `gobject::ObjectExt::unref`. Opens a file in the preferred directory for temporary files (as returned by `g_get_tmp_dir`) and returns a `File` and `FileIOStream` pointing to it. `tmpl` should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is `None`, a default template is used. Unlike the other `File` constructors, this will return `None` if a temporary file could not be created. ## `tmpl` Template for the file name, as in `g_file_open_tmp`, or `None` for a default template ## `iostream` on return, a `FileIOStream` for the created file # Returns a new `File`. Free the returned object with `gobject::ObjectExt::unref`. Constructs a `File` with the given `parse_name` (i.e. something given by `File::get_parse_name`). This operation never fails, but the returned object might not support any I/O operation if the `parse_name` cannot be parsed. ## `parse_name` a file name or path to be parsed # Returns a new `File`. Gets an output stream for appending data to the file. If the file doesn't already exist it is created. By default files created are generally readable by everyone, but if you pass `FileCreateFlags::Private` in `flags` the file will be made readable only to the current user, to the level that is supported on the target filesystem. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. Some file systems don't allow all file names, and may return an `IOErrorEnum::InvalidFilename` error. If the file is a directory the `IOErrorEnum::IsDirectory` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileOutputStream`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously opens `self` for appending. For more details, see `File::append_to` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::append_to_finish` to get the result of the operation. ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file append operation started with `File::append_to_async`. ## `res` `AsyncResult` # Returns a valid `FileOutputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Copies the file `self` to the location specified by `destination`. Can not handle recursive copies of directories. If the flag `FileCopyFlags::Overwrite` is specified an already existing `destination` file is overwritten. If the flag `FileCopyFlags::NofollowSymlinks` is specified then symlinks will be copied as symlinks, otherwise the target of the `self` symlink will be copied. If the flag `FileCopyFlags::AllMetadata` is specified then all the metadata that is possible to copy is copied, not just the default subset (which, for instance, does not include the owner, see `FileInfo`). If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If `progress_callback` is not `None`, then the operation can be monitored by setting this to a `GFileProgressCallback` function. `progress_callback_data` will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. If the `self` file does not exist, then the `IOErrorEnum::NotFound` error is returned, independent on the status of the `destination`. If `FileCopyFlags::Overwrite` is not specified and the target exists, then the error `IOErrorEnum::Exists` is returned. If trying to overwrite a file over a directory, the `IOErrorEnum::IsDirectory` error is returned. If trying to overwrite a directory with a directory the `IOErrorEnum::WouldMerge` error is returned. If the source is a directory and the target does not exist, or `FileCopyFlags::Overwrite` is specified and the target is a file, then the `IOErrorEnum::WouldRecurse` error is returned. If you are interested in copying the `File` object itself (not the on-disk file), see `File::dup`. ## `destination` destination `File` ## `flags` set of `FileCopyFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore ## `progress_callback` function to callback with progress information, or `None` if progress information is not needed ## `progress_callback_data` user data to pass to `progress_callback` # Returns `true` on success, `false` otherwise. Copies the file `self` to the location specified by `destination` asynchronously. For details of the behaviour, see `File::copy`. If `progress_callback` is not `None`, then that function that will be called just like in `File::copy`. The callback will run in the default main context of the thread calling `File::copy_async` — the same context as `callback` is run in. When the operation is finished, `callback` will be called. You can then call `File::copy_finish` to get the result of the operation. ## `destination` destination `File` ## `flags` set of `FileCopyFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `progress_callback` function to callback with progress information, or `None` if progress information is not needed ## `progress_callback_data` user data to pass to `progress_callback` ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Copies the file attributes from `self` to `destination`. Normally only a subset of the file attributes are copied, those that are copies in a normal file copy operation (which for instance does not include e.g. owner). However if `FileCopyFlags::AllMetadata` is specified in `flags`, then all the metadata that is possible to copy is copied. This is useful when implementing move by copy + delete source. ## `destination` a `File` to copy attributes to ## `flags` a set of `FileCopyFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the attributes were copied successfully, `false` otherwise. Finishes copying the file started with `File::copy_async`. ## `res` a `AsyncResult` # Returns a `true` on success, `false` on error. Creates a new file and returns an output stream for writing to it. The file must not already exist. By default files created are generally readable by everyone, but if you pass `FileCreateFlags::Private` in `flags` the file will be made readable only to the current user, to the level that is supported on the target filesystem. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If a file or directory with this name already exists the `IOErrorEnum::Exists` error will be returned. Some file systems don't allow all file names, and may return an `IOErrorEnum::InvalidFilename` error, and if the name is to long `IOErrorEnum::FilenameTooLong` will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileOutputStream` for the newly created file, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist. For more details, see `File::create` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::create_finish` to get the result of the operation. ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file create operation started with `File::create_async`. ## `res` a `AsyncResult` # Returns a `FileOutputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Creates a new file and returns a stream for reading and writing to it. The file must not already exist. By default files created are generally readable by everyone, but if you pass `FileCreateFlags::Private` in `flags` the file will be made readable only to the current user, to the level that is supported on the target filesystem. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If a file or directory with this name already exists, the `IOErrorEnum::Exists` error will be returned. Some file systems don't allow all file names, and may return an `IOErrorEnum::InvalidFilename` error, and if the name is too long, `IOErrorEnum::FilenameTooLong` will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileIOStream` for the newly created file, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist. For more details, see `File::create_readwrite` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::create_readwrite_finish` to get the result of the operation. ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file create operation started with `File::create_readwrite_async`. ## `res` a `AsyncResult` # Returns a `FileIOStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Deletes a file. If the `self` is a directory, it will only be deleted if it is empty. This has the same semantics as `g_unlink`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the file was deleted. `false` otherwise. Asynchronously delete a file. If the `self` is a directory, it will only be deleted if it is empty. This has the same semantics as `g_unlink`. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes deleting a file started with `File::delete_async`. ## `result` a `AsyncResult` # Returns `true` if the file was deleted. `false` otherwise. Duplicates a `File` handle. This operation does not duplicate the actual file or directory represented by the `File`; see `File::copy` if attempting to copy a file. `File::dup` is useful when a second handle is needed to the same underlying file, for use in a separate thread (`File` is not thread-safe). For use within the same thread, use `gobject::ObjectExt::ref` to increment the existing object’s reference count. This call does no blocking I/O. # Returns a new `File` that is a duplicate of the given `File`. Starts an asynchronous eject on a mountable. When this operation has completed, `callback` will be called with `user_user` data, and the operation can be finalized with `File::eject_mountable_with_operation_finish`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation`, or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes an asynchronous eject operation started by `File::eject_mountable_with_operation`. ## `result` a `AsyncResult` # Returns `true` if the `self` was ejected successfully. `false` otherwise. Gets the requested information about the files in a directory. The result is a `FileEnumerator` object that will give out `FileInfo` objects for all the files in the directory. The `attributes` value is a string that specifies the file attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. `attributes` should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query be "standard::*,owner::user". The standard attributes are available as defines, like `G_FILE_ATTRIBUTE_STANDARD_NAME`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. If the file is not a directory, the `IOErrorEnum::NotDirectory` error will be returned. Other errors are possible too. ## `attributes` an attribute query string ## `flags` a set of `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns A `FileEnumerator` if successful, `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously gets the requested information about the files in a directory. The result is a `FileEnumerator` object that will give out `FileInfo` objects for all the files in the directory. For more details, see `File::enumerate_children` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::enumerate_children_finish` to get the result of the operation. ## `attributes` an attribute query string ## `flags` a set of `FileQueryInfoFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an async enumerate children operation. See `File::enumerate_children_async`. ## `res` a `AsyncResult` # Returns a `FileEnumerator` or `None` if an error occurred. Free the returned object with `gobject::ObjectExt::unref`. Checks if the two given `GFiles` refer to the same file. Note that two `GFiles` that differ can still refer to the same file on the filesystem due to various forms of filename aliasing. This call does no blocking I/O. ## `file2` the second `File` # Returns `true` if `self` and `file2` are equal. Gets a `Mount` for the `File`. If the `FileIface` for `self` does not have a mount (e.g. possibly a remote share), `error` will be set to `IOErrorEnum::NotFound` and `None` will be returned. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `Mount` where the `self` is located or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously gets the mount for the file. For more details, see `File::find_enclosing_mount` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::find_enclosing_mount_finish` to get the result of the operation. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous find mount request. See `File::find_enclosing_mount_async`. ## `res` a `AsyncResult` # Returns `Mount` for given `self` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Gets the base name (the last component of the path) for a given `File`. If called for the top level of a system (such as the filesystem root or a uri like sftp://host/) it will return a single directory separator (and on Windows, possibly a drive letter). The base name is a byte string (not UTF-8). It has no defined encoding or rules other than it may not contain zero bytes. If you want to use filenames in a user interface you should use the display name that you can get by requesting the `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME` attribute with `File::query_info`. This call does no blocking I/O. # Returns string containing the `File`'s base name, or `None` if given `File` is invalid. The returned string should be freed with `g_free` when no longer needed. Gets a child of `self` with basename equal to `name`. Note that the file with that specific name might not exist, but you can still have a `File` that points to it. You can use this for instance to create that file. This call does no blocking I/O. ## `name` string containing the child's basename # Returns a `File` to a child specified by `name`. Free the returned object with `gobject::ObjectExt::unref`. Gets the child of `self` for a given `display_name` (i.e. a UTF-8 version of the name). If this function fails, it returns `None` and `error` will be set. This is very useful when constructing a `File` for a new file and the user entered the filename in the user interface, for instance when you select a directory and type a filename in the file selector. This call does no blocking I/O. ## `display_name` string to a possible child # Returns a `File` to the specified child, or `None` if the display name couldn't be converted. Free the returned object with `gobject::ObjectExt::unref`. Gets the parent directory for the `self`. If the `self` represents the root directory of the file system, then `None` will be returned. This call does no blocking I/O. # Returns a `File` structure to the parent of the given `File` or `None` if there is no parent. Free the returned object with `gobject::ObjectExt::unref`. Gets the parse name of the `self`. A parse name is a UTF-8 string that describes the file such that one can get the `File` back using `File::parse_name`. This is generally used to show the `File` as a nice full-pathname kind of string in a user interface, like in a location entry. For local files with names that can safely be converted to UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped). This call does no blocking I/O. # Returns a string containing the `File`'s parse name. The returned string should be freed with `g_free` when no longer needed. Gets the local pathname for `File`, if one exists. If non-`None`, this is guaranteed to be an absolute, canonical path. It might contain symlinks. This call does no blocking I/O. # Returns string containing the `File`'s path, or `None` if no such path exists. The returned string should be freed with `g_free` when no longer needed. Gets the path for `descendant` relative to `self`. This call does no blocking I/O. ## `descendant` input `File` # Returns string with the relative path from `descendant` to `self`, or `None` if `descendant` doesn't have `self` as prefix. The returned string should be freed with `g_free` when no longer needed. Gets the URI for the `self`. This call does no blocking I/O. # Returns a string containing the `File`'s URI. The returned string should be freed with `g_free` when no longer needed. Gets the URI scheme for a `File`. RFC 3986 decodes the scheme as: ```text URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ``` Common schemes include "file", "http", "ftp", etc. This call does no blocking I/O. # Returns a string containing the URI scheme for the given `File`. The returned string should be freed with `g_free` when no longer needed. Checks if `self` has a parent, and optionally, if it is `parent`. If `parent` is `None` then this function returns `true` if `self` has any parent at all. If `parent` is non-`None` then `true` is only returned if `self` is an immediate child of `parent`. ## `parent` the parent to check for, or `None` # Returns `true` if `self` is an immediate child of `parent` (or any parent in the case that `parent` is `None`). Checks whether `self` has the prefix specified by `prefix`. In other words, if the names of initial elements of `self`'s pathname match `prefix`. Only full pathname elements are matched, so a path like /foo is not considered a prefix of /foobar, only of /foo/bar. A `File` is not a prefix of itself. If you want to check for equality, use `File::equal`. This call does no I/O, as it works purely on names. As such it can sometimes return `false` even if `self` is inside a `prefix` (from a filesystem point of view), because the prefix of `self` is an alias of `prefix`. ## `prefix` input `File` # Returns `true` if the `files`'s parent, grandparent, etc is `prefix`, `false` otherwise. Checks to see if a `File` has a given URI scheme. This call does no blocking I/O. ## `uri_scheme` a string containing a URI scheme # Returns `true` if `File`'s backend supports the given URI scheme, `false` if URI scheme is `None`, not supported, or `File` is invalid. Creates a hash value for a `File`. This call does no blocking I/O. # Returns 0 if `self` is not a valid `File`, otherwise an integer that can be used as hash value for the `File`. This function is intended for easily hashing a `File` to add to a `glib::HashTable` or similar data structure. Checks to see if a file is native to the platform. A native file is one expressed in the platform-native filename format, e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, as it might be on a locally mounted remote filesystem. On some systems non-native files may be available using the native filesystem via a userspace filesystem (FUSE), in these cases this call will return `false`, but `File::get_path` will still return a native path. This call does no blocking I/O. # Returns `true` if `self` is native Loads the contents of `self` and returns it as `glib::Bytes`. If `self` is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling `File::load_contents` and `glib::Bytes::new_take`. For resources, `etag_out` will be set to `None`. The data contained in the resulting `glib::Bytes` is always zero-terminated, but this is not included in the `glib::Bytes` length. The resulting `glib::Bytes` should be freed with `glib::Bytes::unref` when no longer in use. Feature: `v2_56` ## `cancellable` a `Cancellable` or `None` ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns a `glib::Bytes` or `None` and `error` is set Asynchronously loads the contents of `self` as `glib::Bytes`. If `self` is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling `File::load_contents_async` and `glib::Bytes::new_take`. `callback` should call `File::load_bytes_finish` to get the result of this asynchronous operation. See `File::load_bytes` for more information. Feature: `v2_56` ## `cancellable` a `Cancellable` or `None` ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Completes an asynchronous request to `File::load_bytes_async`. For resources, `etag_out` will be set to `None`. The data contained in the resulting `glib::Bytes` is always zero-terminated, but this is not included in the `glib::Bytes` length. The resulting `glib::Bytes` should be freed with `glib::Bytes::unref` when no longer in use. See `File::load_bytes` for more information. Feature: `v2_56` ## `result` a `AsyncResult` provided to the callback ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns a `glib::Bytes` or `None` and `error` is set Loads the content of the file into memory. The data is always zero-terminated, but this is not included in the resultant `length`. The returned `content` should be freed with `g_free` when no longer needed. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `contents` a location to place the contents of the file ## `length` a location to place the length of the contents of the file, or `None` if the length is not needed ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns `true` if the `self`'s contents were successfully loaded. `false` if there were errors. Starts an asynchronous load of the `self`'s contents. For more details, see `File::load_contents` which is the synchronous version of this call. When the load operation has completed, `callback` will be called with `user` data. To finish the operation, call `File::load_contents_finish` with the `AsyncResult` returned by the `callback`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous load of the `self`'s contents. The contents are placed in `contents`, and `length` is set to the size of the `contents` string. The `content` should be freed with `g_free` when no longer needed. If `etag_out` is present, it will be set to the new entity tag for the `self`. ## `res` a `AsyncResult` ## `contents` a location to place the contents of the file ## `length` a location to place the length of the contents of the file, or `None` if the length is not needed ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns `true` if the load was successful. If `false` and `error` is present, it will be set appropriately. Reads the partial contents of a file. A `GFileReadMoreCallback` should be used to stop reading from the file when appropriate, else this function will behave exactly as `File::load_contents_async`. This operation can be finished by `File::load_partial_contents_finish`. Users of this function should be aware that `user_data` is passed to both the `read_more_callback` and the `callback`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `read_more_callback` a `GFileReadMoreCallback` to receive partial data and to specify whether further data should be read ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to the callback functions Finishes an asynchronous partial load operation that was started with `File::load_partial_contents_async`. The data is always zero-terminated, but this is not included in the resultant `length`. The returned `content` should be freed with `g_free` when no longer needed. ## `res` a `AsyncResult` ## `contents` a location to place the contents of the file ## `length` a location to place the length of the contents of the file, or `None` if the length is not needed ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns `true` if the load was successful. If `false` and `error` is present, it will be set appropriately. Creates a directory. Note that this will only create a child directory of the immediate parent directory of the path or URI given by the `File`. To recursively create directories, see `File::make_directory_with_parents`. This function will fail if the parent directory does not exist, setting `error` to `IOErrorEnum::NotFound`. If the file system doesn't support creating directories, this function will fail, setting `error` to `IOErrorEnum::NotSupported`. For a local `File` the newly created directory will have the default (current) ownership and permissions of the current process. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` on successful creation, `false` otherwise. Asynchronously creates a directory. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous directory creation, started with `File::make_directory_async`. ## `result` a `AsyncResult` # Returns `true` on successful directory creation, `false` otherwise. Creates a directory and any parent directories that may not exist similar to 'mkdir -p'. If the file system does not support creating directories, this function will fail, setting `error` to `IOErrorEnum::NotSupported`. If the directory itself already exists, this function will fail setting `error` to `IOErrorEnum::Exists`, unlike the similar `g_mkdir_with_parents`. For a local `File` the newly created directories will have the default (current) ownership and permissions of the current process. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if all directories have been successfully created, `false` otherwise. Creates a symbolic link named `self` which contains the string `symlink_value`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `symlink_value` a string with the path for the target of the new symlink ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` on the creation of a new symlink, `false` otherwise. Recursively measures the disk usage of `self`. This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered (including things like symbolic links). By default, errors are only reported against the toplevel file itself. Errors found while recursing are silently ignored, unless `G_FILE_DISK_USAGE_REPORT_ALL_ERRORS` is given in `flags`. The returned size, `disk_usage`, is in bytes and should be formatted with `g_format_size` in order to get something reasonable for showing in a user interface. `progress_callback` and `progress_data` can be given to request periodic progress updates while scanning. See the documentation for `GFileMeasureProgressCallback` for information about when and how the callback will be invoked. ## `flags` `FileMeasureFlags` ## `cancellable` optional `Cancellable` ## `progress_callback` a `GFileMeasureProgressCallback` ## `progress_data` user_data for `progress_callback` ## `disk_usage` the number of bytes of disk space used ## `num_dirs` the number of directories encountered ## `num_files` the number of non-directories encountered # Returns `true` if successful, with the out parameters set. `false` otherwise, with `error` set. Recursively measures the disk usage of `self`. This is the asynchronous version of `File::measure_disk_usage`. See there for more information. ## `flags` `FileMeasureFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` ## `progress_callback` a `GFileMeasureProgressCallback` ## `progress_data` user_data for `progress_callback` ## `callback` a `GAsyncReadyCallback` to call when complete ## `user_data` the data to pass to callback function Collects the results from an earlier call to `File::measure_disk_usage_async`. See `File::measure_disk_usage` for more information. ## `result` the `AsyncResult` passed to your `GAsyncReadyCallback` ## `disk_usage` the number of bytes of disk space used ## `num_dirs` the number of directories encountered ## `num_files` the number of non-directories encountered # Returns `true` if successful, with the out parameters set. `false` otherwise, with `error` set. Obtains a file or directory monitor for the given file, depending on the type of the file. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `flags` a set of `FileMonitorFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileMonitor` for the given `self`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Obtains a directory monitor for the given file. This may fail if directory monitoring is not supported. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. It does not make sense for `flags` to contain `FileMonitorFlags::WatchHardLinks`, since hard links can not be made to directories. It is not possible to monitor all the files in a directory for changes made via hard links; if you want to do this then you must register individual watches with `File::monitor`. ## `flags` a set of `FileMonitorFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileMonitor` for the given `self`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If `flags` contains `FileMonitorFlags::WatchHardLinks` then the monitor will also attempt to report changes made to the file via another filename (ie, a hard link). Without this flag, you can only rely on changes made through the filename contained in `self` to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the `FileMonitor` backend and/or filesystem type. ## `flags` a set of `FileMonitorFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileMonitor` for the given `self`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Starts a `mount_operation`, mounting the volume that contains the file `self`. When this operation has completed, `callback` will be called with `user_user` data, and the operation can be finalized with `File::mount_enclosing_volume_finish`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation` or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes a mount operation started by `File::mount_enclosing_volume`. ## `result` a `AsyncResult` # Returns `true` if successful. If an error has occurred, this function will return `false` and set `error` appropriately if present. Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using `mount_operation`, you can request callbacks when, for instance, passwords are needed during authentication. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::mount_mountable_finish` to get the result of the operation. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation`, or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes a mount operation. See `File::mount_mountable` for details. Finish an asynchronous mount operation that was started with `File::mount_mountable`. ## `result` a `AsyncResult` # Returns a `File` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Tries to move the file or directory `self` to the location specified by `destination`. If native move operations are supported then this is used, otherwise a copy + delete fallback is used. The native implementation may support moving directories (for instance on moves inside the same filesystem), but the fallback code does not. If the flag `FileCopyFlags::Overwrite` is specified an already existing `destination` file is overwritten. If the flag `FileCopyFlags::NofollowSymlinks` is specified then symlinks will be copied as symlinks, otherwise the target of the `self` symlink will be copied. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If `progress_callback` is not `None`, then the operation can be monitored by setting this to a `GFileProgressCallback` function. `progress_callback_data` will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. If the `self` file does not exist, then the `IOErrorEnum::NotFound` error is returned, independent on the status of the `destination`. If `FileCopyFlags::Overwrite` is not specified and the target exists, then the error `IOErrorEnum::Exists` is returned. If trying to overwrite a file over a directory, the `IOErrorEnum::IsDirectory` error is returned. If trying to overwrite a directory with a directory the `IOErrorEnum::WouldMerge` error is returned. If the source is a directory and the target does not exist, or `FileCopyFlags::Overwrite` is specified and the target is a file, then the `IOErrorEnum::WouldRecurse` error may be returned (if the native move operation isn't available). ## `destination` `File` pointing to the destination location ## `flags` set of `FileCopyFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore ## `progress_callback` `GFileProgressCallback` function for updates ## `progress_callback_data` gpointer to user data for the callback function # Returns `true` on successful move, `false` otherwise. Opens an existing file for reading and writing. The result is a `FileIOStream` that can be used to read and write the contents of the file. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. If the file is a directory, the `IOErrorEnum::IsDirectory` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. ## `cancellable` a `Cancellable` # Returns `FileIOStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously opens `self` for reading and writing. For more details, see `File::open_readwrite` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::open_readwrite_finish` to get the result of the operation. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file read operation started with `File::open_readwrite_async`. ## `res` a `AsyncResult` # Returns a `FileIOStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Exactly like `File::get_path`, but caches the result via `gobject::ObjectExt::set_qdata_full`. This is useful for example in C applications which mix `g_file_*` APIs with native ones. It also avoids an extra duplicated string when possible, so will be generally more efficient. This call does no blocking I/O. Feature: `v2_56` # Returns string containing the `File`'s path, or `None` if no such path exists. The returned string is owned by `self`. Polls a file of type `FileType::Mountable`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::mount_mountable_finish` to get the result of the operation. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes a poll operation. See `File::poll_mountable` for details. Finish an asynchronous poll operation that was polled with `File::poll_mountable`. ## `result` a `AsyncResult` # Returns `true` if the operation finished successfully. `false` otherwise. Returns the `AppInfo` that is registered as the default application to handle the file specified by `self`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `AppInfo` if the handle was found, `None` if there were errors. When you are done with it, release it with `gobject::ObjectExt::unref` Utility function to check if a particular file exists. This is implemented using `File::query_info` and as such does blocking I/O. Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) and then execute something based on the outcome of that, because the file might have been created or removed in between the operations. The general approach to handling that is to not check, but just do the operation and handle the errors as they come. As an example of race-free checking, take the case of reading a file, and if it doesn't exist, creating it. There are two racy versions: read it, and on error create it; and: check if it exists, if not create it. These can both result in two processes creating the file (with perhaps a partially written file as the result). The correct approach is to always try to create the file with `File::create` which will either atomically create the file or fail with a `IOErrorEnum::Exists` error. However, in many cases an existence check is useful in a user interface, for instance to make a menu item sensitive/insensitive, so that you don't have to fool users that something is possible and then just show an error dialog. If you do this, you should make sure to also handle the errors that can happen due to races when you execute the operation. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the file exists (and can be detected without error), `false` otherwise (or if cancelled). Utility function to inspect the `FileType` of a file. This is implemented using `File::query_info` and as such does blocking I/O. The primary use case of this method is to check if a file is a regular file, directory, or symlink. ## `flags` a set of `FileQueryInfoFlags` passed to `File::query_info` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns The `FileType` of the file and `FileType::Unknown` if the file does not exist Similar to `File::query_info`, but obtains information about the filesystem the `self` is on, rather than the file itself. For instance the amount of space available and the type of the filesystem. The `attributes` value is a string that specifies the attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. `attributes` should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "filesystem::*" means all attributes in the filesystem namespace. The standard namespace for filesystem attributes is "filesystem". Common attributes of interest are `G_FILE_ATTRIBUTE_FILESYSTEM_SIZE` (the total size of the filesystem in bytes), `G_FILE_ATTRIBUTE_FILESYSTEM_FREE` (number of bytes available), and `G_FILE_ATTRIBUTE_FILESYSTEM_TYPE` (type of the filesystem). If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `attributes` an attribute query string ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileInfo` or `None` if there was an error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously gets the requested information about the filesystem that the specified `self` is on. The result is a `FileInfo` object that contains key-value attributes (such as type or size for the file). For more details, see `File::query_filesystem_info` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::query_info_finish` to get the result of the operation. ## `attributes` an attribute query string ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous filesystem info query. See `File::query_filesystem_info_async`. ## `res` a `AsyncResult` # Returns `FileInfo` for given `self` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Gets the requested information about specified `self`. The result is a `FileInfo` object that contains key-value attributes (such as the type or size of the file). The `attributes` value is a string that specifies the file attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. `attributes` should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query be "standard::*,owner::user". The standard attributes are available as defines, like `G_FILE_ATTRIBUTE_STANDARD_NAME`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass `FileQueryInfoFlags::NofollowSymlinks` in `flags` the information about the symlink itself will be returned. Also, for symlinks that point to non-existing files the information about the symlink itself will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `attributes` an attribute query string ## `flags` a set of `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileInfo` for the given `self`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously gets the requested information about specified `self`. The result is a `FileInfo` object that contains key-value attributes (such as type or size for the file). For more details, see `File::query_info` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::query_info_finish` to get the result of the operation. ## `attributes` an attribute query string ## `flags` a set of `FileQueryInfoFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file info query. See `File::query_info_async`. ## `res` a `AsyncResult` # Returns `FileInfo` for given `self` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Obtain the list of settable attributes for the file. Returns the type and full attribute name of all the attributes that can be set on this file. This doesn't mean setting it will always succeed though, you might get an access failure, or some specific file may not support a specific attribute. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileAttributeInfoList` describing the settable attributes. When you are done with it, release it with `FileAttributeInfoList::unref` Obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace). If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileAttributeInfoList` describing the writable namespaces. When you are done with it, release it with `FileAttributeInfoList::unref` Opens a file for reading. The result is a `FileInputStream` that can be used to read the contents of the file. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. If the file is a directory, the `IOErrorEnum::IsDirectory` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `cancellable` a `Cancellable` # Returns `FileInputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously opens `self` for reading. For more details, see `File::read` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::read_finish` to get the result of the operation. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file read operation started with `File::read_async`. ## `res` a `AsyncResult` # Returns a `FileInputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. This will try to replace the file in the safest way possible so that any errors during the writing will not affect an already existing copy of the file. For instance, for local files it may write to a temporary file and then atomically rename over the destination when the stream is closed. By default files created are generally readable by everyone, but if you pass `FileCreateFlags::Private` in `flags` the file will be made readable only to the current user, to the level that is supported on the target filesystem. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If you pass in a non-`None` `etag` value and `self` already exists, then this value is compared to the current entity tag of the file, and if they differ an `IOErrorEnum::WrongEtag` error is returned. This generally means that the file has been changed since you last read it. You can get the new etag from `FileOutputStreamExt::get_etag` after you've finished writing and closed the `FileOutputStream`. When you load a new file you can use `FileInputStreamExt::query_info` to get the etag of the file. If `make_backup` is `true`, this function will attempt to make a backup of the current file before overwriting it. If this fails a `IOErrorEnum::CantCreateBackup` error will be returned. If you want to replace anyway, try again with `make_backup` set to `false`. If the file is a directory the `IOErrorEnum::IsDirectory` error will be returned, and if the file is some other form of non-regular file then a `IOErrorEnum::NotRegularFile` error will be returned. Some file systems don't allow all file names, and may return an `IOErrorEnum::InvalidFilename` error, and if the name is to long `IOErrorEnum::FilenameTooLong` will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `etag` an optional [entity tag][gfile-etag] for the current `File`, or `None` to ignore ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileOutputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first. For more details, see `File::replace` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::replace_finish` to get the result of the operation. ## `etag` an [entity tag][gfile-etag] for the current `File`, or `None` to ignore ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Replaces the contents of `self` with `contents` of `length` bytes. If `etag` is specified (not `None`), any existing file must have that etag, or the error `IOErrorEnum::WrongEtag` will be returned. If `make_backup` is `true`, this function will attempt to make a backup of `self`. Internally, it uses `File::replace`, so will try to replace the file contents in the safest way possible. For example, atomic renames are used when replacing local files’ contents. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. The returned `new_etag` can be used to verify that the file hasn't changed the next time it is saved over. ## `contents` a string containing the new contents for `self` ## `length` the length of `contents` in bytes ## `etag` the old [entity-tag][gfile-etag] for the document, or `None` ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `new_etag` a location to a new [entity tag][gfile-etag] for the document. This should be freed with `g_free` when no longer needed, or `None` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if successful. If an error has occurred, this function will return `false` and set `error` appropriately if present. Starts an asynchronous replacement of `self` with the given `contents` of `length` bytes. `etag` will replace the document's current entity tag. When this operation has completed, `callback` will be called with `user_user` data, and the operation can be finalized with `File::replace_contents_finish`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If `make_backup` is `true`, this function will attempt to make a backup of `self`. Note that no copy of `content` will be made, so it must stay valid until `callback` is called. See `File::replace_contents_bytes_async` for a `glib::Bytes` version that will automatically hold a reference to the contents (without copying) for the duration of the call. ## `contents` string of contents to replace the file with ## `length` the length of `contents` in bytes ## `etag` a new [entity tag][gfile-etag] for the `self`, or `None` ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Same as `File::replace_contents_async` but takes a `glib::Bytes` input instead. This function will keep a ref on `contents` until the operation is done. Unlike `File::replace_contents_async` this allows forgetting about the content without waiting for the callback. When this operation has completed, `callback` will be called with `user_user` data, and the operation can be finalized with `File::replace_contents_finish`. ## `contents` a `glib::Bytes` ## `etag` a new [entity tag][gfile-etag] for the `self`, or `None` ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous replace of the given `self`. See `File::replace_contents_async`. Sets `new_etag` to the new entity tag for the document, if present. ## `res` a `AsyncResult` ## `new_etag` a location of a new [entity tag][gfile-etag] for the document. This should be freed with `g_free` when it is no longer needed, or `None` # Returns `true` on success, `false` on failure. Finishes an asynchronous file replace operation started with `File::replace_async`. ## `res` a `AsyncResult` # Returns a `FileOutputStream`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created. For details about the behaviour, see `File::replace` which does the same thing but returns an output stream only. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. ## `etag` an optional [entity tag][gfile-etag] for the current `File`, or `None` to ignore ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileIOStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first. For more details, see `File::replace_readwrite` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::replace_readwrite_finish` to get the result of the operation. ## `etag` an [entity tag][gfile-etag] for the current `File`, or `None` to ignore ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file replace operation started with `File::replace_readwrite_async`. ## `res` a `AsyncResult` # Returns a `FileIOStream`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Resolves a relative path for `self` to an absolute path. This call does no blocking I/O. ## `relative_path` a given relative path string # Returns `File` to the resolved path. `None` if `relative_path` is `None` or if `self` is invalid. Free the returned object with `gobject::ObjectExt::unref`. Sets an attribute in the file with attribute name `attribute` to `value`. Some attributes can be unset by setting `type_` to `FileAttributeType::Invalid` and `value_p` to `None`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `type_` The type of the attribute ## `value_p` a pointer to the value (or the pointer itself if the type is a pointer type) ## `flags` a set of `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the attribute was set, `false` otherwise. Sets `attribute` of type `FileAttributeType::ByteString` to `value`. If `attribute` is of a different type, this operation will fail, returning `false`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a string containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set to `value` in the `self`, `false` otherwise. Sets `attribute` of type `FileAttributeType::Int32` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a `gint32` containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set to `value` in the `self`, `false` otherwise. Sets `attribute` of type `FileAttributeType::Int64` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a `guint64` containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set, `false` otherwise. Sets `attribute` of type `FileAttributeType::String` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a string containing the attribute's value ## `flags` `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set, `false` otherwise. Sets `attribute` of type `FileAttributeType::Uint32` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a `guint32` containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set to `value` in the `self`, `false` otherwise. Sets `attribute` of type `FileAttributeType::Uint64` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a `guint64` containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set to `value` in the `self`, `false` otherwise. Asynchronously sets the attributes of `self` with `info`. For more details, see `File::set_attributes_from_info`, which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::set_attributes_finish` to get the result of the operation. ## `info` a `FileInfo` ## `flags` a `FileQueryInfoFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` ## `user_data` a `gpointer` Finishes setting an attribute started in `File::set_attributes_async`. ## `result` a `AsyncResult` ## `info` a `FileInfo` # Returns `true` if the attributes were set correctly, `false` otherwise. Tries to set all attributes in the `FileInfo` on the target values, not stopping on the first error. If there is any error during this operation then `error` will be set to the first error. Error on particular fields are flagged by setting the "status" field in the attribute value to `FileAttributeStatus::ErrorSetting`, which means you can also detect further errors. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `info` a `FileInfo` ## `flags` `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `false` if there was any error, `true` otherwise. Renames `self` to the specified display name. The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and the `self` is renamed to this. If you want to implement a rename operation in the user interface the edit name (`G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME`) should be used as the initial value in the rename widget, and then the result after editing should be passed to `File::set_display_name`. On success the resulting converted filename is returned. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `display_name` a string ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `File` specifying what `self` was renamed to, or `None` if there was an error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously sets the display name for a given `File`. For more details, see `File::set_display_name` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::set_display_name_finish` to get the result of the operation. ## `display_name` a string ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes setting a display name started with `File::set_display_name_async`. ## `res` a `AsyncResult` # Returns a `File` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Starts a file of type `FileType::Mountable`. Using `start_operation`, you can request callbacks when, for instance, passwords are needed during authentication. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::mount_mountable_finish` to get the result of the operation. ## `flags` flags affecting the operation ## `start_operation` a `MountOperation`, or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes a start operation. See `File::start_mountable` for details. Finish an asynchronous start operation that was started with `File::start_mountable`. ## `result` a `AsyncResult` # Returns `true` if the operation finished successfully. `false` otherwise. Stops a file of type `FileType::Mountable`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::stop_mountable_finish` to get the result of the operation. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation`, or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes an stop operation, see `File::stop_mountable` for details. Finish an asynchronous stop operation that was started with `File::stop_mountable`. ## `result` a `AsyncResult` # Returns `true` if the operation finished successfully. `false` otherwise. Checks if `self` supports [thread-default contexts][g-main-context-push-thread-default-context]. If this returns `false`, you cannot perform asynchronous operations on `self` in a thread that has a thread-default context. # Returns Whether or not `self` supports thread-default contexts. Sends `self` to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Not all file systems support trashing, so this call can return the `IOErrorEnum::NotSupported` error. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` on successful trash, `false` otherwise. Asynchronously sends `self` to the Trash location, if possible. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file trashing operation, started with `File::trash_async`. ## `result` a `AsyncResult` # Returns `true` on successful trash, `false` otherwise. Unmounts a file of type `FileType::Mountable`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::unmount_mountable_finish` to get the result of the operation. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation`, or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes an unmount operation, see `File::unmount_mountable_with_operation` for details. Finish an asynchronous unmount operation that was started with `File::unmount_mountable_with_operation`. ## `result` a `AsyncResult` # Returns `true` if the operation finished successfully. `false` otherwise. Determines if a string matches a file attribute. Creates a new file attribute matcher, which matches attributes against a given string. `GFileAttributeMatchers` are reference counted structures, and are created with a reference count of 1. If the number of references falls to 0, the `FileAttributeMatcher` is automatically destroyed. The `attribute` string should be formatted with specific keys separated from namespaces with a double colon. Several "namespace::key" strings may be concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). The wildcard "*" may be used to match all keys and namespaces, or "namespace::*" will match all keys in a given namespace. ## Examples of file attribute matcher strings and results - `"*"`: matches all attributes. - `"standard::is-hidden"`: matches only the key is-hidden in the standard namespace. - `"standard::type,unix::*"`: matches the type key in the standard namespace and all keys in the unix namespace. ## `attributes` an attribute string to match. # Returns a `FileAttributeMatcher` Checks if the matcher will match all of the keys in a given namespace. This will always return `true` if a wildcard character is in use (e.g. if matcher was created with "standard::*" and `ns` is "standard", or if matcher was created using "*" and namespace is anything.) TODO: this is awkwardly worded. ## `ns` a string containing a file attribute namespace. # Returns `true` if the matcher matches all of the entries in the given `ns`, `false` otherwise. Gets the next matched attribute from a `FileAttributeMatcher`. # Returns a string containing the next attribute or `None` if no more attribute exist. Checks if an attribute will be matched by an attribute matcher. If the matcher was created with the "*" matching string, this function will always return `true`. ## `attribute` a file attribute key. # Returns `true` if `attribute` matches `self`. `false` otherwise. Checks if a attribute matcher only matches a given attribute. Always returns `false` if "*" was used when creating the matcher. ## `attribute` a file attribute key. # Returns `true` if the matcher only matches `attribute`. `false` otherwise. References a file attribute matcher. # Returns a `FileAttributeMatcher`. Subtracts all attributes of `subtract` from `self` and returns a matcher that supports those attributes. Note that currently it is not possible to remove a single attribute when the `self` matches the whole namespace - or remove a namespace or attribute when the matcher matches everything. This is a limitation of the current implementation, but may be fixed in the future. ## `subtract` The matcher to subtract # Returns A file attribute matcher matching all attributes of `self` that are not matched by `subtract` Prints what the matcher is matching against. The format will be equal to the format passed to `FileAttributeMatcher::new`. The output however, might not be identical, as the matcher may decide to use a different order or omit needless parts. # Returns a string describing the attributes the matcher matches against or `None` if `self` was `None`. Unreferences `self`. If the reference count falls below 1, the `self` is automatically freed. Used by `File::set_attributes_from_info` when setting file attributes. Attribute value is unset (empty). Attribute value is set. Indicates an error in setting the value. The data types for file attributes. indicates an invalid or uninitalized type. a null terminated UTF8 string. a zero terminated string of non-zero bytes. a boolean value. an unsigned 4-byte/32-bit integer. a signed 4-byte/32-bit integer. an unsigned 8-byte/64-bit integer. a signed 8-byte/64-bit integer. a `gobject::Object`. a `None` terminated char **. Since 2.22 GFileIOStream provides io streams that both read and write to the same file handle. GFileIOStream implements `Seekable`, which allows the io stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations. To find the position of a file io stream, use `Seekable::tell`. To find out if a file io stream supports seeking, use `Seekable::can_seek`. To position a file io stream, use `Seekable::seek`. To find out if a file io stream supports truncating, use `Seekable::can_truncate`. To truncate a file io stream, use `Seekable::truncate`. The default implementation of all the `FileIOStream` operations and the implementation of `Seekable` just call into the same operations on the output stream. # Implements [`FileIOStreamExt`](trait.FileIOStreamExt.html), [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html) Trait containing all `FileIOStream` methods. # Implementors [`FileIOStream`](struct.FileIOStream.html) Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. # Returns the entity tag for the stream. Queries a file io stream for the given `attributes`. This function blocks while querying the stream. For the asynchronous version of this function, see `FileIOStreamExt::query_info_async`. While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with `IOErrorEnum::Pending`. Can fail if the stream was already closed (with `error` being set to `IOErrorEnum::Closed`), the stream has pending operations (with `error` being set to `IOErrorEnum::Pending`), or if querying info is not supported for the stream's interface (with `error` being set to `IOErrorEnum::NotSupported`). I all cases of failure, `None` will be returned. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be set, and `None` will be returned. ## `attributes` a file attribute query string. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `FileInfo` for the `self`, or `None` on error. Asynchronously queries the `self` for a `FileInfo`. When completed, `callback` will be called with a `AsyncResult` which can be used to finish the operation with `FileIOStreamExt::query_info_finish`. For the synchronous version of this function, see `FileIOStreamExt::query_info`. ## `attributes` a file attribute query string. ## `io_priority` the [I/O priority][gio-GIOScheduler] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finalizes the asynchronous query started by `FileIOStreamExt::query_info_async`. ## `result` a `AsyncResult`. # Returns A `FileInfo` for the finished query. `FileIcon` specifies an icon by pointing to an image file to be used as icon. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IconExt`](trait.IconExt.html), [`LoadableIconExt`](trait.LoadableIconExt.html) Creates a new icon for a file. ## `file` a `File`. # Returns a `Icon` for the given `file`, or `None` on error. Gets the `File` associated with the given `self`. # Returns a `File`, or `None`. The file containing the icon. The file containing the icon. Functionality for manipulating basic metadata for files. `FileInfo` implements methods for getting information that all files should contain, and allows for manipulation of extended attributes. See [GFileAttribute][gio-GFileAttribute] for more information on how GIO handles file attributes. To obtain a `FileInfo` for a `File`, use `File::query_info` (or its async variant). To obtain a `FileInfo` for a file input or output stream, use `FileInputStreamExt::query_info` or `FileOutputStreamExt::query_info` (or their async variants). To change the actual attributes of a file, you should then set the attribute in the `FileInfo` and call `File::set_attributes_from_info` or `File::set_attributes_async` on a GFile. However, not all attributes can be changed in the file. For instance, the actual size of a file cannot be changed via `FileInfo::set_size`. You may call `File::query_settable_attributes` and `File::query_writable_namespaces` to discover the settable attributes of a particular file at runtime. `FileAttributeMatcher` allows for searching through a `FileInfo` for attributes. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new file info structure. # Returns a `FileInfo`. Clears the status information from `self`. First clears all of the [GFileAttribute][gio-GFileAttribute] of `dest_info`, and then copies all of the file attributes from `self` to `dest_info`. ## `dest_info` destination to copy attributes to. Duplicates a file info structure. # Returns a duplicate `FileInfo` of `self`. Gets the value of a attribute, formated as a string. This escapes things as needed to make the string valid utf8. ## `attribute` a file attribute key. # Returns a UTF-8 string associated with the given `attribute`. When you're done with the string it must be freed with `g_free`. Gets the value of a boolean attribute. If the attribute does not contain a boolean value, `false` will be returned. ## `attribute` a file attribute key. # Returns the boolean value contained within the attribute. Gets the value of a byte string attribute. If the attribute does not contain a byte string, `None` will be returned. ## `attribute` a file attribute key. # Returns the contents of the `attribute` value as a byte string, or `None` otherwise. Gets the attribute type, value and status for an attribute key. ## `attribute` a file attribute key ## `type_` return location for the attribute type, or `None` ## `value_pp` return location for the attribute value, or `None`; the attribute value will not be `None` ## `status` return location for the attribute status, or `None` # Returns `true` if `self` has an attribute named `attribute`, `false` otherwise. Gets a signed 32-bit integer contained within the attribute. If the attribute does not contain a signed 32-bit integer, or is invalid, 0 will be returned. ## `attribute` a file attribute key. # Returns a signed 32-bit integer from the attribute. Gets a signed 64-bit integer contained within the attribute. If the attribute does not contain an signed 64-bit integer, or is invalid, 0 will be returned. ## `attribute` a file attribute key. # Returns a signed 64-bit integer from the attribute. Gets the value of a `gobject::Object` attribute. If the attribute does not contain a `gobject::Object`, `None` will be returned. ## `attribute` a file attribute key. # Returns a `gobject::Object` associated with the given `attribute`, or `None` otherwise. Gets the attribute status for an attribute key. ## `attribute` a file attribute key # Returns a `FileAttributeStatus` for the given `attribute`, or `FileAttributeStatus::Unset` if the key is invalid. Gets the value of a string attribute. If the attribute does not contain a string, `None` will be returned. ## `attribute` a file attribute key. # Returns the contents of the `attribute` value as a UTF-8 string, or `None` otherwise. Gets the value of a stringv attribute. If the attribute does not contain a stringv, `None` will be returned. ## `attribute` a file attribute key. # Returns the contents of the `attribute` value as a stringv, or `None` otherwise. Do not free. These returned strings are UTF-8. Gets the attribute type for an attribute key. ## `attribute` a file attribute key. # Returns a `FileAttributeType` for the given `attribute`, or `FileAttributeType::Invalid` if the key is not set. Gets an unsigned 32-bit integer contained within the attribute. If the attribute does not contain an unsigned 32-bit integer, or is invalid, 0 will be returned. ## `attribute` a file attribute key. # Returns an unsigned 32-bit integer from the attribute. Gets a unsigned 64-bit integer contained within the attribute. If the attribute does not contain an unsigned 64-bit integer, or is invalid, 0 will be returned. ## `attribute` a file attribute key. # Returns a unsigned 64-bit integer from the attribute. Gets the file's content type. # Returns a string containing the file's content type. Returns the `glib::DateTime` representing the deletion date of the file, as available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, `None` is returned. # Returns a `glib::DateTime`, or `None`. Gets a display name for a file. # Returns a string containing the display name. Gets the edit name for a file. # Returns a string containing the edit name. Gets the [entity tag][gfile-etag] for a given `FileInfo`. See `G_FILE_ATTRIBUTE_ETAG_VALUE`. # Returns a string containing the value of the "etag:value" attribute. Gets a file's type (whether it is a regular file, symlink, etc). This is different from the file's content type, see `FileInfo::get_content_type`. # Returns a `FileType` for the given file. Gets the icon for a file. # Returns `Icon` for the given `self`. Checks if a file is a backup file. # Returns `true` if file is a backup file, `false` otherwise. Checks if a file is hidden. # Returns `true` if the file is a hidden file, `false` otherwise. Checks if a file is a symlink. # Returns `true` if the given `self` is a symlink. Gets the modification time of the current `self` and sets it in `result`. ## `result` a `glib::TimeVal`. Gets the name for a file. # Returns a string containing the file name. Gets the file's size. # Returns a `goffset` containing the file's size. Gets the value of the sort_order attribute from the `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. # Returns a `gint32` containing the value of the "standard::sort_order" attribute. Gets the symbolic icon for a file. # Returns `Icon` for the given `self`. Gets the symlink target for a given `FileInfo`. # Returns a string containing the symlink target. Checks if a file info structure has an attribute named `attribute`. ## `attribute` a file attribute key. # Returns `true` if `Ginfo` has an attribute named `attribute`, `false` otherwise. Checks if a file info structure has an attribute in the specified `name_space`. ## `name_space` a file attribute namespace. # Returns `true` if `Ginfo` has an attribute in `name_space`, `false` otherwise. Lists the file info structure's attributes. ## `name_space` a file attribute key's namespace, or `None` to list all attributes. # Returns a null-terminated array of strings of all of the possible attribute types for the given `name_space`, or `None` on error. Removes all cases of `attribute` from `self` if it exists. ## `attribute` a file attribute key. Sets the `attribute` to contain the given value, if possible. To unset the attribute, use `FileAttributeType::Invalid` for `type_`. ## `attribute` a file attribute key. ## `type_` a `FileAttributeType` ## `value_p` pointer to the value Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a boolean value. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a byte string. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a signed 32-bit integer Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` attribute name to set. ## `attr_value` int64 value to set attribute to. Sets `mask` on `self` to match specific attribute types. ## `mask` a `FileAttributeMatcher`. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a `gobject::Object`. Sets the attribute status for an attribute key. This is only needed by external code that implement `File::set_attributes_from_info` or similar functions. The attribute must exist in `self` for this to work. Otherwise `false` is returned and `self` is unchanged. ## `attribute` a file attribute key ## `status` a `FileAttributeStatus` # Returns `true` if the status was changed, `false` if the key was not set. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a UTF-8 string. Sets the `attribute` to contain the given `attr_value`, if possible. Sinze: 2.22 ## `attribute` a file attribute key ## `attr_value` a `None` terminated array of UTF-8 strings. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` an unsigned 32-bit integer. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` an unsigned 64-bit integer. Sets the content type attribute for a given `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE`. ## `content_type` a content type. See [GContentType][gio-GContentType] Sets the display name for the current `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME`. ## `display_name` a string containing a display name. Sets the edit name for the current file. See `G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME`. ## `edit_name` a string containing an edit name. Sets the file type in a `FileInfo` to `type_`. See `G_FILE_ATTRIBUTE_STANDARD_TYPE`. ## `type_` a `FileType`. Sets the icon for a given `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_ICON`. ## `icon` a `Icon`. Sets the "is_hidden" attribute in a `FileInfo` according to `is_hidden`. See `G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN`. ## `is_hidden` a `gboolean`. Sets the "is_symlink" attribute in a `FileInfo` according to `is_symlink`. See `G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK`. ## `is_symlink` a `gboolean`. Sets the `G_FILE_ATTRIBUTE_TIME_MODIFIED` attribute in the file info to the given time value. ## `mtime` a `glib::TimeVal`. Sets the name attribute for the current `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_NAME`. ## `name` a string containing a name. Sets the `G_FILE_ATTRIBUTE_STANDARD_SIZE` attribute in the file info to the given size. ## `size` a `goffset` containing the file's size. Sets the sort order attribute in the file info structure. See `G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. ## `sort_order` a sort order integer. Sets the symbolic icon for a given `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON`. ## `icon` a `Icon`. Sets the `G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET` attribute in the file info to the given symlink target. ## `symlink_target` a static string containing a path to a symlink target. Unsets a mask set by `FileInfo::set_attribute_mask`, if one is set. GFileInputStream provides input streams that take their content from a file. GFileInputStream implements `Seekable`, which allows the input stream to jump to arbitrary positions in the file, provided the filesystem of the file allows it. To find the position of a file input stream, use `Seekable::tell`. To find out if a file input stream supports seeking, use `Seekable::can_seek`. To position a file input stream, use `Seekable::seek`. # Implements [`FileInputStreamExt`](trait.FileInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `FileInputStream` methods. # Implementors [`FileInputStream`](struct.FileInputStream.html) Queries a file input stream the given `attributes`. This function blocks while querying the stream. For the asynchronous (non-blocking) version of this function, see `FileInputStreamExt::query_info_async`. While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with `IOErrorEnum::Pending`. ## `attributes` a file attribute query string. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `FileInfo`, or `None` on error. Queries the stream information asynchronously. When the operation is finished `callback` will be called. You can then call `FileInputStreamExt::query_info_finish` to get the result of the operation. For the synchronous version of this function, see `FileInputStreamExt::query_info`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be set ## `attributes` a file attribute query string. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous info query operation. ## `result` a `AsyncResult`. # Returns `FileInfo`. Monitors a file or directory for changes. To obtain a `FileMonitor` for a file or directory, use `File::monitor`, `File::monitor_file`, or `File::monitor_directory`. To get informed about changes to the file or directory you are monitoring, connect to the `FileMonitor::changed` signal. The signal will be emitted in the [thread-default main context][g-main-context-push-thread-default] of the thread that the monitor was created in (though if the global default main context is blocked, this may cause notifications to be blocked even if the thread-default context is still running). # Implements [`FileMonitorExt`](trait.FileMonitorExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `FileMonitor` methods. # Implementors [`FileMonitor`](struct.FileMonitor.html) Cancels a file monitor. # Returns always `true` Emits the `FileMonitor::changed` signal if a change has taken place. Should be called from file monitor implementations only. Implementations are responsible to call this method from the [thread-default main context][g-main-context-push-thread-default] of the thread that the monitor was created in. ## `child` a `File`. ## `other_file` a `File`. ## `event_type` a set of `FileMonitorEvent` flags. Returns whether the monitor is canceled. # Returns `true` if monitor is canceled. `false` otherwise. Sets the rate limit to which the `self` will report consecutive change events to the same file. ## `limit_msecs` a non-negative integer with the limit in milliseconds to poll for changes Emitted when `file` has been changed. If using `FileMonitorFlags::WatchMoves` on a directory monitor, and the information is available (and if supported by the backend), `event_type` may be `FileMonitorEvent::Renamed`, `FileMonitorEvent::MovedIn` or `FileMonitorEvent::MovedOut`. In all cases `file` will be a child of the monitored directory. For renames, `file` will be the old name and `other_file` is the new name. For "moved in" events, `file` is the name of the file that appeared and `other_file` is the old name that it was moved from (in another directory). For "moved out" events, `file` is the name of the file that used to be in this directory and `other_file` is the name of the file at its new location. It makes sense to treat `FileMonitorEvent::MovedIn` as equivalent to `FileMonitorEvent::Created` and `FileMonitorEvent::MovedOut` as equivalent to `FileMonitorEvent::Deleted`, with extra information. `FileMonitorEvent::Renamed` is equivalent to a delete/create pair. This is exactly how the events will be reported in the case that the `FileMonitorFlags::WatchMoves` flag is not in use. If using the deprecated flag `FileMonitorFlags::SendMoved` flag and `event_type` is `FileMonitorEvent::Moved`, `file` will be set to a `File` containing the old path, and `other_file` will be set to a `File` containing the new path. In all the other cases, `other_file` will be set to `None`. ## `file` a `File`. ## `other_file` a `File` or `None`. ## `event_type` a `FileMonitorEvent`. Specifies what type of event a monitor event is. a file changed. a hint that this was probably the last change in a set of changes. a file was deleted. a file was created. a file attribute was changed. the file location will soon be unmounted. the file location was unmounted. the file was moved -- only sent if the (deprecated) `FileMonitorFlags::SendMoved` flag is set the file was renamed within the current directory -- only sent if the `FileMonitorFlags::WatchMoves` flag is set. Since: 2.46. the file was moved into the monitored directory from another location -- only sent if the `FileMonitorFlags::WatchMoves` flag is set. Since: 2.46. the file was moved out of the monitored directory to another location -- only sent if the `FileMonitorFlags::WatchMoves` flag is set. Since: 2.46 GFileOutputStream provides output streams that write their content to a file. GFileOutputStream implements `Seekable`, which allows the output stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations. To find the position of a file output stream, use `Seekable::tell`. To find out if a file output stream supports seeking, use `Seekable::can_seek`.To position a file output stream, use `Seekable::seek`. To find out if a file output stream supports truncating, use `Seekable::can_truncate`. To truncate a file output stream, use `Seekable::truncate`. # Implements [`FileOutputStreamExt`](trait.FileOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `FileOutputStream` methods. # Implementors [`FileOutputStream`](struct.FileOutputStream.html) Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. # Returns the entity tag for the stream. Queries a file output stream for the given `attributes`. This function blocks while querying the stream. For the asynchronous version of this function, see `FileOutputStreamExt::query_info_async`. While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with `IOErrorEnum::Pending`. Can fail if the stream was already closed (with `error` being set to `IOErrorEnum::Closed`), the stream has pending operations (with `error` being set to `IOErrorEnum::Pending`), or if querying info is not supported for the stream's interface (with `error` being set to `IOErrorEnum::NotSupported`). In all cases of failure, `None` will be returned. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be set, and `None` will be returned. ## `attributes` a file attribute query string. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `FileInfo` for the `self`, or `None` on error. Asynchronously queries the `self` for a `FileInfo`. When completed, `callback` will be called with a `AsyncResult` which can be used to finish the operation with `FileOutputStreamExt::query_info_finish`. For the synchronous version of this function, see `FileOutputStreamExt::query_info`. ## `attributes` a file attribute query string. ## `io_priority` the [I/O priority][gio-GIOScheduler] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finalizes the asynchronous query started by `FileOutputStreamExt::query_info_async`. ## `result` a `AsyncResult`. # Returns A `FileInfo` for the finished query. Indicates the file's on-disk type. File's type is unknown. File handle represents a regular file. File handle represents a directory. File handle represents a symbolic link (Unix systems). File is a "special" file, such as a socket, fifo, block device, or character device. File is a shortcut (Windows systems). File is a mountable location. Completes partial file and directory names given a partial string by looking in the file system for clues. Can return a list of possible completion strings for widget implementations. # Implements [`FilenameCompleterExt`](trait.FilenameCompleterExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `FilenameCompleter` methods. # Implementors [`FilenameCompleter`](struct.FilenameCompleter.html) Creates a new filename completer. # Returns a `FilenameCompleter`. Obtains a completion for `initial_text` from `self`. ## `initial_text` text to be completed. # Returns a completed string, or `None` if no completion exists. This string is not owned by GIO, so remember to `g_free` it when finished. Gets an array of completion strings for a given initial text. ## `initial_text` text to be completed. # Returns array of strings with possible completions for `initial_text`. This array must be freed by `g_strfreev` when finished. If `dirs_only` is `true`, `self` will only complete directory names, and not file names. ## `dirs_only` a `gboolean`. Emitted when the file name completion information comes available. Base class for input stream implementations that perform some kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping. # Implements [`FilterInputStreamExt`](trait.FilterInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `FilterInputStream` methods. # Implementors [`BufferedInputStream`](struct.BufferedInputStream.html), [`ConverterInputStream`](struct.ConverterInputStream.html), [`FilterInputStream`](struct.FilterInputStream.html) Gets the base stream for the filter stream. # Returns a `InputStream`. Returns whether the base stream will be closed when `self` is closed. # Returns `true` if the base stream will be closed. Sets whether the base stream will be closed when `self` is closed. ## `close_base` `true` to close the base stream. Base class for output stream implementations that perform some kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping. # Implements [`FilterOutputStreamExt`](trait.FilterOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `FilterOutputStream` methods. # Implementors [`BufferedOutputStream`](struct.BufferedOutputStream.html), [`ConverterOutputStream`](struct.ConverterOutputStream.html), [`DataOutputStream`](struct.DataOutputStream.html), [`FilterOutputStream`](struct.FilterOutputStream.html) Gets the base stream for the filter stream. # Returns a `OutputStream`. Returns whether the base stream will be closed when `self` is closed. # Returns `true` if the base stream will be closed. Sets whether the base stream will be closed when `self` is closed. ## `close_base` `true` to close the base stream. Error codes returned by GIO functions. Note that this domain may be extended in future GLib releases. In general, new error codes either only apply to new APIs, or else replace `IOErrorEnum::Failed` in cases that were not explicitly distinguished before. You should therefore avoid writing code like ```C if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_FAILED)) { // Assume that this is EPRINTERONFIRE ... } ``` but should instead treat all unrecognized error codes the same as `IOErrorEnum::Failed`. Generic error condition for when an operation fails and no more specific `IOErrorEnum` value is defined. File not found. File already exists. File is a directory. File is not a directory. File is a directory that isn't empty. File is not a regular file. File is not a symbolic link. File cannot be mounted. Filename is too many characters. Filename is invalid or contains invalid characters. File contains too many symbolic links. No space left on drive. Invalid argument. Permission denied. Operation (or one of its parameters) not supported File isn't mounted. File is already mounted. File was closed. Operation was cancelled. See `Cancellable`. Operations are still pending. File is read only. Backup couldn't be created. File's Entity Tag was incorrect. Operation timed out. Operation would be recursive. File is busy. Operation would block. Host couldn't be found (remote operations). Operation would merge files. Operation failed and a helper program has already interacted with the user. Do not display any error dialog. The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20 The object has not been initialized. Since 2.22 The requested address is already in use. Since 2.22 Need more input to finish operation. Since 2.24 The input data was invalid. Since 2.24 A remote object generated an error that doesn't correspond to a locally registered `glib::Error` error domain. Use `DBusError::get_remote_error` to extract the D-Bus error name and `DBusError::strip_remote_error` to fix up the message so it matches what was received on the wire. Since 2.26. Host unreachable. Since 2.26 Network unreachable. Since 2.26 Connection refused. Since 2.26 Connection to proxy server failed. Since 2.26 Proxy authentication failed. Since 2.26 Proxy server needs authentication. Since 2.26 Proxy connection is not allowed by ruleset. Since 2.26 Broken pipe. Since 2.36 Connection closed by peer. Note that this is the same code as `IOErrorEnum::BrokenPipe`; before 2.44 some "connection closed" errors returned `IOErrorEnum::BrokenPipe`, but others returned `IOErrorEnum::Failed`. Now they should all return the same value, which has this more logical name. Since 2.44. Transport endpoint is not connected. Since 2.44 Message too large. Since 2.48. GIOStream represents an object that has both read and write streams. Generally the two streams act as separate input and output streams, but they share some common resources and state. For instance, for seekable streams, both streams may use the same position. Examples of `IOStream` objects are `SocketConnection`, which represents a two-way network connection; and `FileIOStream`, which represents a file handle opened in read-write mode. To do the actual reading and writing you need to get the substreams with `IOStreamExt::get_input_stream` and `IOStreamExt::get_output_stream`. The `IOStream` object owns the input and the output streams, not the other way around, so keeping the substreams alive will not keep the `IOStream` object alive. If the `IOStream` object is freed it will be closed, thus closing the substreams, so even if the substreams stay alive they will always return `IOErrorEnum::Closed` for all operations. To close a stream use `IOStreamExt::close` which will close the common stream object and also the individual substreams. You can also close the substreams themselves. In most cases this only marks the substream as closed, so further I/O on it fails but common state in the `IOStream` may still be open. However, some streams may support "half-closed" states where one direction of the stream is actually shut down. Operations on `GIOStreams` cannot be started while another operation on the `IOStream` or its substreams is in progress. Specifically, an application can read from the `InputStream` and write to the `OutputStream` simultaneously (either in separate threads, or as asynchronous operations in the same thread), but an application cannot start any `IOStream` operation while there is a `IOStream`, `InputStream` or `OutputStream` operation in progress, and an application can’t start any `InputStream` or `OutputStream` operation while there is a `IOStream` operation in progress. This is a product of individual stream operations being associated with a given `glib::MainContext` (the thread-default context at the time the operation was started), rather than entire streams being associated with a single `glib::MainContext`. GIO may run operations on `GIOStreams` from other (worker) threads, and this may be exposed to application code in the behaviour of wrapper streams, such as `BufferedInputStream` or `TlsConnection`. With such wrapper APIs, application code may only run operations on the base (wrapped) stream when the wrapper stream is idle. Note that the semantics of such operations may not be well-defined due to the state the wrapper stream leaves the base stream in (though they are guaranteed not to crash). # Implements [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `IOStream` methods. # Implementors [`FileIOStream`](struct.FileIOStream.html), [`IOStream`](struct.IOStream.html), [`SimpleIOStream`](struct.SimpleIOStream.html), [`SocketConnection`](struct.SocketConnection.html), [`TlsConnection`](struct.TlsConnection.html) Finishes an asynchronous io stream splice operation. ## `result` a `AsyncResult`. # Returns `true` on success, `false` otherwise. Clears the pending flag on `self`. Closes the stream, releasing resources related to it. This will also close the individual input and output streams, if they are not already closed. Once the stream is closed, all other operations will return `IOErrorEnum::Closed`. Closing a stream multiple times will not return an error. Closing a stream will automatically flush any outstanding buffers in the stream. Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details. On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return `IOErrorEnum::Closed` for all operations. Still, it is important to check and report the error to the user, otherwise there might be a loss of data as all data might not be written. If `cancellable` is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. Cancelling a close will still leave the stream closed, but some streams can use a faster close that doesn't block to e.g. check errors. The default implementation of this method just calls close on the individual input/output streams. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` on success, `false` on failure Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished `callback` will be called. You can then call `IOStreamExt::close_finish` to get the result of the operation. For behaviour details see `IOStreamExt::close`. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. ## `io_priority` the io priority of the request ## `cancellable` optional cancellable object ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Closes a stream. ## `result` a `AsyncResult` # Returns `true` if stream was successfully closed, `false` otherwise. Gets the input stream for this object. This is used for reading. # Returns a `InputStream`, owned by the `IOStream`. Do not free. Gets the output stream for this object. This is used for writing. # Returns a `OutputStream`, owned by the `IOStream`. Do not free. Checks if a stream has pending actions. # Returns `true` if `self` has pending actions. Checks if a stream is closed. # Returns `true` if the stream is closed. Sets `self` to have actions pending. If the pending flag is already set or `self` is closed, it will return `false` and set `error`. # Returns `true` if pending was previously unset and is now set. Asyncronously splice the output stream of `self` to the input stream of `stream2`, and splice the output stream of `stream2` to the input stream of `self`. When the operation is finished `callback` will be called. You can then call `IOStream::splice_finish` to get the result of the operation. ## `stream2` a `IOStream`. ## `flags` a set of `IOStreamSpliceFlags`. ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`. ## `user_data` user data passed to `callback`. `Icon` is a very minimal interface for icons. It provides functions for checking the equality of two icons, hashing of icons and serializing an icon to and from strings. `Icon` does not provide the actual pixmap for the icon as this is out of GIO's scope, however implementations of `Icon` may contain the name of an icon (see `ThemedIcon`), or the path to an icon (see `LoadableIcon`). To obtain a hash of a `Icon`, see `Icon::hash`. To check if two `GIcons` are equal, see `Icon::equal`. For serializing a `Icon`, use `Icon::serialize` and `Icon::deserialize`. If you want to consume `Icon` (for example, in a toolkit) you must be prepared to handle at least the three following cases: `LoadableIcon`, `ThemedIcon` and `EmblemedIcon`. It may also make sense to have fast-paths for other cases (like handling ``GdkPixbuf`` directly, for example) but all compliant `Icon` implementations outside of GIO must implement `LoadableIcon`. If your application or library provides one or more `Icon` implementations you need to ensure that your new implementation also implements `LoadableIcon`. Additionally, you must provide an implementation of `Icon::serialize` that gives a result that is understood by `Icon::deserialize`, yielding one of the built-in icon types. # Implements [`IconExt`](trait.IconExt.html) Trait containing all `Icon` methods. # Implementors [`BytesIcon`](struct.BytesIcon.html), [`Emblem`](struct.Emblem.html), [`EmblemedIcon`](struct.EmblemedIcon.html), [`FileIcon`](struct.FileIcon.html), [`Icon`](struct.Icon.html), [`LoadableIcon`](struct.LoadableIcon.html), [`ThemedIcon`](struct.ThemedIcon.html) Deserializes a `Icon` previously serialized using `Icon::serialize`. ## `value` a `glib::Variant` created with `Icon::serialize` # Returns a `Icon`, or `None` when deserialization fails. Gets a hash for an icon. ## `icon` `gconstpointer` to an icon object. # Returns a `guint` containing a hash for the `icon`, suitable for use in a `glib::HashTable` or similar data structure. Generate a `Icon` instance from `str`. This function can fail if `str` is not valid - see `Icon::to_string` for discussion. If your application or library provides one or more `Icon` implementations you need to ensure that each `glib::Type` is registered with the type system prior to calling `Icon::new_for_string`. ## `str` A string obtained via `Icon::to_string`. # Returns An object implementing the `Icon` interface or `None` if `error` is set. Checks if two icons are equal. ## `icon2` pointer to the second `Icon`. # Returns `true` if `self` is equal to `icon2`. `false` otherwise. Serializes a `Icon` into a `glib::Variant`. An equivalent `Icon` can be retrieved back by calling `Icon::deserialize` on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the `glib::Variant` between processes on the same machine, (as opposed to over the network), and within the same file system namespace. # Returns a `glib::Variant`, or `None` when serialization fails. Generates a textual representation of `self` that can be used for serialization such as when passing `self` to a different process or saving it to persistent storage. Use `Icon::new_for_string` to get `self` back from the returned string. The encoding of the returned string is proprietary to `Icon` except in the following two cases - If `self` is a `FileIcon`, the returned string is a native path (such as `/path/to/my icon.png`) without escaping if the `File` for `self` is a native file. If the file is not native, the returned string is the result of `File::get_uri` (such as `sftp://path/to/my%20icon.png`). - If `self` is a `ThemedIcon` with exactly one name and no fallbacks, the encoding is simply the name (such as `network-server`). # Returns An allocated NUL-terminated UTF8 string or `None` if `self` can't be serialized. Use `g_free` to free. `InetAddress` represents an IPv4 or IPv6 internet address. Use `ResolverExt::lookup_by_name` or `ResolverExt::lookup_by_name_async` to look up the `InetAddress` for a hostname. Use `ResolverExt::lookup_by_address` or `ResolverExt::lookup_by_address_async` to look up the hostname for a `InetAddress`. To actually connect to a remote host, you will need a `InetSocketAddress` (which includes a `InetAddress` as well as a port number). # Implements [`InetAddressExt`](trait.InetAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `InetAddress` methods. # Implementors [`InetAddress`](struct.InetAddress.html) Creates a `InetAddress` for the "any" address (unassigned/"don't care") for `family`. ## `family` the address family # Returns a new `InetAddress` corresponding to the "any" address for `family`. Free the returned object with `gobject::ObjectExt::unref`. Creates a new `InetAddress` from the given `family` and `bytes`. `bytes` should be 4 bytes for `SocketFamily::Ipv4` and 16 bytes for `SocketFamily::Ipv6`. ## `bytes` raw address data ## `family` the address family of `bytes` # Returns a new `InetAddress` corresponding to `family` and `bytes`. Free the returned object with `gobject::ObjectExt::unref`. Parses `string` as an IP address and creates a new `InetAddress`. ## `string` a string representation of an IP address # Returns a new `InetAddress` corresponding to `string`, or `None` if `string` could not be parsed. Free the returned object with `gobject::ObjectExt::unref`. Creates a `InetAddress` for the loopback address for `family`. ## `family` the address family # Returns a new `InetAddress` corresponding to the loopback address for `family`. Free the returned object with `gobject::ObjectExt::unref`. Checks if two `InetAddress` instances are equal, e.g. the same address. ## `other_address` Another `InetAddress`. # Returns `true` if `self` and `other_address` are equal, `false` otherwise. Gets `self`'s family # Returns `self`'s family Tests whether `self` is the "any" address for its family. # Returns `true` if `self` is the "any" address for its family. Tests whether `self` is a link-local address (that is, if it identifies a host on a local network that is not connected to the Internet). # Returns `true` if `self` is a link-local address. Tests whether `self` is the loopback address for its family. # Returns `true` if `self` is the loopback address for its family. Tests whether `self` is a global multicast address. # Returns `true` if `self` is a global multicast address. Tests whether `self` is a link-local multicast address. # Returns `true` if `self` is a link-local multicast address. Tests whether `self` is a node-local multicast address. # Returns `true` if `self` is a node-local multicast address. Tests whether `self` is an organization-local multicast address. # Returns `true` if `self` is an organization-local multicast address. Tests whether `self` is a site-local multicast address. # Returns `true` if `self` is a site-local multicast address. Tests whether `self` is a multicast address. # Returns `true` if `self` is a multicast address. Tests whether `self` is a site-local address such as 10.0.0.1 (that is, the address identifies a host on a local network that can not be reached directly from the Internet, but which may have outgoing Internet connectivity via a NAT or firewall). # Returns `true` if `self` is a site-local address. Gets the size of the native raw binary address for `self`. This is the size of the data that you get from `InetAddress::to_bytes`. # Returns the number of bytes used for the native version of `self`. Gets the raw binary address data from `self`. # Returns a pointer to an internal array of the bytes in `self`, which should not be modified, stored, or freed. The size of this array can be gotten with `InetAddressExt::get_native_size`. Converts `self` to string form. # Returns a representation of `self` as a string, which should be freed after use. Whether this is the "any" address for its family. See `InetAddressExt::get_is_any`. Whether this is a link-local address. See `InetAddressExt::get_is_link_local`. Whether this is the loopback address for its family. See `InetAddressExt::get_is_loopback`. Whether this is a global multicast address. See `InetAddressExt::get_is_mc_global`. Whether this is a link-local multicast address. See `InetAddressExt::get_is_mc_link_local`. Whether this is a node-local multicast address. See `InetAddressExt::get_is_mc_node_local`. Whether this is an organization-local multicast address. See `InetAddressExt::get_is_mc_org_local`. Whether this is a site-local multicast address. See `InetAddressExt::get_is_mc_site_local`. Whether this is a multicast address. See `InetAddressExt::get_is_multicast`. Whether this is a site-local address. See `InetAddressExt::get_is_loopback`. `InetAddressMask` represents a range of IPv4 or IPv6 addresses described by a base address and a length indicating how many bits of the base address are relevant for matching purposes. These are often given in string form. Eg, "10.0.0.0/8", or "fe80::/10". # Implements [`InetAddressMaskExt`](trait.InetAddressMaskExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `InetAddressMask` methods. # Implementors [`InetAddressMask`](struct.InetAddressMask.html) Creates a new `InetAddressMask` representing all addresses whose first `length` bits match `addr`. ## `addr` a `InetAddress` ## `length` number of bits of `addr` to use # Returns a new `InetAddressMask`, or `None` on error Parses `mask_string` as an IP address and (optional) length, and creates a new `InetAddressMask`. The length, if present, is delimited by a "/". If it is not present, then the length is assumed to be the full length of the address. ## `mask_string` an IP address or address/length string # Returns a new `InetAddressMask` corresponding to `string`, or `None` on error. Tests if `self` and `mask2` are the same mask. ## `mask2` another `InetAddressMask` # Returns whether `self` and `mask2` are the same mask Gets `self`'s base address # Returns `self`'s base address Gets the `SocketFamily` of `self`'s address # Returns the `SocketFamily` of `self`'s address Gets `self`'s length # Returns `self`'s length Tests if `address` falls within the range described by `self`. ## `address` a `InetAddress` # Returns whether `address` falls within the range described by `self`. Converts `self` back to its corresponding string form. # Returns a string corresponding to `self`. An IPv4 or IPv6 socket address; that is, the combination of a `InetAddress` and a port number. # Implements [`InetSocketAddressExt`](trait.InetSocketAddressExt.html), [`SocketAddressExt`](trait.SocketAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `InetSocketAddress` methods. # Implementors [`InetSocketAddress`](struct.InetSocketAddress.html), [`ProxyAddress`](struct.ProxyAddress.html) Creates a new `InetSocketAddress` for `address` and `port`. ## `address` a `InetAddress` ## `port` a port number # Returns a new `InetSocketAddress` Creates a new `InetSocketAddress` for `address` and `port`. If `address` is an IPv6 address, it can also contain a scope ID (separated from the address by a `%`). ## `address` the string form of an IP address ## `port` a port number # Returns a new `InetSocketAddress`, or `None` if `address` cannot be parsed. Gets `self`'s `InetAddress`. # Returns the `InetAddress` for `self`, which must be `gobject::ObjectExt::ref`'d if it will be stored Gets the `sin6_flowinfo` field from `self`, which must be an IPv6 address. # Returns the flowinfo field Gets `self`'s port. # Returns the port for `self` Gets the `sin6_scope_id` field from `self`, which must be an IPv6 address. # Returns the scope id field The `sin6_flowinfo` field, for IPv6 addresses. The `sin6_flowinfo` field, for IPv6 addresses. `InputStream` has functions to read from a stream (`InputStream::read`), to close a stream (`InputStreamExt::close`) and to skip some content (`InputStreamExt::skip`). To copy the content of an input stream to an output stream without manually handling the reads and writes, use `OutputStreamExt::splice`. See the documentation for `IOStream` for details of thread safety of streaming APIs. All of these functions have async variants too. # Implements [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `InputStream` methods. # Implementors [`FileInputStream`](struct.FileInputStream.html), [`FilterInputStream`](struct.FilterInputStream.html), [`InputStream`](struct.InputStream.html), [`MemoryInputStream`](struct.MemoryInputStream.html), [`PollableInputStream`](struct.PollableInputStream.html), [`UnixInputStream`](struct.UnixInputStream.html) Clears the pending flag on `self`. Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return `IOErrorEnum::Closed`. Closing a stream multiple times will not return an error. Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details. On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return `IOErrorEnum::Closed` for all operations. Still, it is important to check and report the error to the user. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. Cancelling a close will still leave the stream closed, but some streams can use a faster close that doesn't block to e.g. check errors. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` on success, `false` on failure Requests an asynchronous closes of the stream, releasing resources related to it. When the operation is finished `callback` will be called. You can then call `InputStreamExt::close_finish` to get the result of the operation. For behaviour details see `InputStreamExt::close`. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional cancellable object ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes closing a stream asynchronously, started from `InputStreamExt::close_async`. ## `result` a `AsyncResult`. # Returns `true` if the stream was closed successfully. Checks if an input stream has pending actions. # Returns `true` if `self` has pending actions. Checks if an input stream is closed. # Returns `true` if the stream is closed. Tries to read `count` bytes from the stream into the buffer starting at `buffer`. Will block during this read. If count is zero returns zero and does nothing. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if `count` is zero), but never otherwise. The returned `buffer` is not a nul-terminated string, it can contain nul bytes at any position, and this function doesn't nul-terminate the `buffer`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and `error` is set accordingly. ## `buffer` a buffer to read data into (which should be at least count bytes long). ## `count` the number of bytes that will be read from the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns Number of bytes read, or -1 on error, or 0 on end of file. Tries to read `count` bytes from the stream into the buffer starting at `buffer`. Will block during this read. This function is similar to `InputStream::read`, except it tries to read as many bytes as requested, only stopping on an error or end of stream. On a successful read of `count` bytes, or if we reached the end of the stream, `true` is returned, and `bytes_read` is set to the number of bytes read into `buffer`. If there is an error during the operation `false` is returned and `error` is set to indicate the error status. As a special exception to the normal conventions for functions that use `glib::Error`, if this function returns `false` (and sets `error`) then `bytes_read` will be set to the number of bytes that were successfully read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around `InputStream::read`. ## `buffer` a buffer to read data into (which should be at least count bytes long). ## `count` the number of bytes that will be read from the stream ## `bytes_read` location to store the number of bytes that was read from the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` on success, `false` if there was an error Request an asynchronous read of `count` bytes from the stream into the buffer starting at `buffer`. This is the asynchronous equivalent of `InputStream::read_all`. Call `InputStreamExt::read_all_finish` to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`. Feature: `v2_44` ## `buffer` a buffer to read data into (which should be at least count bytes long) ## `count` the number of bytes that will be read from the stream ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous stream read operation started with `InputStream::read_all_async`. As a special exception to the normal conventions for functions that use `glib::Error`, if this function returns `false` (and sets `error`) then `bytes_read` will be set to the number of bytes that were successfully read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around `InputStream::read_async`. Feature: `v2_44` ## `result` a `AsyncResult` ## `bytes_read` location to store the number of bytes that was read from the stream # Returns `true` on success, `false` if there was an error Request an asynchronous read of `count` bytes from the stream into the buffer starting at `buffer`. When the operation is finished `callback` will be called. You can then call `InputStreamExt::read_finish` to get the result of the operation. During an async request no other sync and async calls are allowed on `self`, and will result in `IOErrorEnum::Pending` errors. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, the number of bytes read into the buffer will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to read as many bytes as requested. Zero is returned on end of file (or if `count` is zero), but never otherwise. Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. ## `buffer` a buffer to read data into (which should be at least count bytes long). ## `count` the number of bytes that will be read from the stream ## `io_priority` the [I/O priority][io-priority] of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Like `InputStream::read`, this tries to read `count` bytes from the stream in a blocking fashion. However, rather than reading into a user-supplied buffer, this will create a new `glib::Bytes` containing the data that was read. This may be easier to use from language bindings. If count is zero, returns a zero-length `glib::Bytes` and does nothing. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, a new `glib::Bytes` is returned. It is not an error if the size of this object is not the same as the requested size, as it can happen e.g. near the end of a file. A zero-length `glib::Bytes` is returned on end of file (or if `count` is zero), but never otherwise. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error `None` is returned and `error` is set accordingly. ## `count` maximum number of bytes that will be read from the stream. Common values include 4096 and 8192. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a new `glib::Bytes`, or `None` on error Request an asynchronous read of `count` bytes from the stream into a new `glib::Bytes`. When the operation is finished `callback` will be called. You can then call `InputStreamExt::read_bytes_finish` to get the result of the operation. During an async request no other sync and async calls are allowed on `self`, and will result in `IOErrorEnum::Pending` errors. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, the new `glib::Bytes` will be passed to the callback. It is not an error if this is smaller than the requested size, as it can happen e.g. near the end of a file, but generally we try to read as many bytes as requested. Zero is returned on end of file (or if `count` is zero), but never otherwise. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`. ## `count` the number of bytes that will be read from the stream ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous stream read-into-`glib::Bytes` operation. ## `result` a `AsyncResult`. # Returns the newly-allocated `glib::Bytes`, or `None` on error Finishes an asynchronous stream read operation. ## `result` a `AsyncResult`. # Returns number of bytes read in, or -1 on error, or 0 on end of file. Sets `self` to have actions pending. If the pending flag is already set or `self` is closed, it will return `false` and set `error`. # Returns `true` if pending was previously unset and is now set. Tries to skip `count` bytes from the stream. Will block during the operation. This is identical to `InputStream::read`, from a behaviour standpoint, but the bytes that are skipped are not returned to the user. Some streams have an implementation that is more efficient than reading the data. This function is optional for inherited classes, as the default implementation emulates it using read. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. ## `count` the number of bytes that will be skipped from the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns Number of bytes skipped, or -1 on error Request an asynchronous skip of `count` bytes from the stream. When the operation is finished `callback` will be called. You can then call `InputStreamExt::skip_finish` to get the result of the operation. During an async request no other sync and async calls are allowed, and will result in `IOErrorEnum::Pending` errors. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, the number of bytes skipped will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to skip as many bytes as requested. Zero is returned on end of file (or if `count` is zero), but never otherwise. Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one, you must override all. ## `count` the number of bytes that will be skipped from the stream ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes a stream skip operation. ## `result` a `AsyncResult`. # Returns the size of the bytes skipped, or %-1 on error. `ListModel` is an interface that represents a mutable list of `GObjects`. Its main intention is as a model for various widgets in user interfaces, such as list views, but it can also be used as a convenient method of returning lists of data, with support for updates. Each object in the list may also report changes in itself via some mechanism (normally the `gobject::Object::notify` signal). Taken together with the `ListModel::items-changed` signal, this provides for a list that can change its membership, and in which the members can change their individual properties. A good example would be the list of visible wireless network access points, where each access point can report dynamic properties such as signal strength. It is important to note that the `ListModel` itself does not report changes to the individual items. It only reports changes to the list membership. If you want to observe changes to the objects themselves then you need to connect signals to the objects that you are interested in. All items in a `ListModel` are of (or derived from) the same type. `ListModel::get_item_type` returns that type. The type may be an interface, in which case all objects in the list must implement it. The semantics are close to that of an array: `ListModel::get_n_items` returns the number of items in the list and `ListModel::get_item` returns an item at a (0-based) position. In order to allow implementations to calculate the list length lazily, you can also iterate over items: starting from 0, repeatedly call `ListModel::get_item` until it returns `None`. An implementation may create objects lazily, but must take care to return the same object for a given position until all references to it are gone. On the other side, a consumer is expected only to hold references on objects that are currently "user visible", in order to faciliate the maximum level of laziness in the implementation of the list and to reduce the required number of signal connections at a given time. This interface is intended only to be used from a single thread. The thread in which it is appropriate to use it depends on the particular implementation, but typically it will be from the thread that owns the [thread-default main context][g-main-context-push-thread-default] in effect at the time that the model was created. Feature: `v2_44` # Implements [`ListModelExt`](trait.ListModelExt.html) Trait containing all `ListModel` methods. Feature: `v2_44` # Implementors [`ListModel`](struct.ListModel.html), [`ListStore`](struct.ListStore.html) Get the item at `position`. If `position` is greater than the number of items in `self`, `None` is returned. `None` is never returned for an index that is smaller than the length of the list. See `ListModel::get_n_items`. Feature: `v2_44` ## `position` the position of the item to fetch # Returns the item at `position`. Gets the type of the items in `self`. All items returned from `g_list_model_get_type` are of that type or a subtype, or are an implementation of that interface. The item type of a `ListModel` can not change during the life of the model. Feature: `v2_44` # Returns the `glib::Type` of the items contained in `self`. Gets the number of items in `self`. Depending on the model implementation, calling this function may be less efficient than iterating the list with increasing values for `position` until `ListModel::get_item` returns `None`. Feature: `v2_44` # Returns the number of items in `self`. Get the item at `position`. If `position` is greater than the number of items in `self`, `None` is returned. `None` is never returned for an index that is smaller than the length of the list. See `ListModel::get_n_items`. Feature: `v2_44` ## `position` the position of the item to fetch # Returns the object at `position`. Emits the `ListModel::items-changed` signal on `self`. This function should only be called by classes implementing `ListModel`. It has to be called after the internal representation of `self` has been updated, because handlers connected to this signal might query the new state of the list. Implementations must only make changes to the model (as visible to its consumer) in places that will not cause problems for that consumer. For models that are driven directly by a write API (such as `ListStore`), changes can be reported in response to uses of that API. For models that represent remote data, changes should only be made from a fresh mainloop dispatch. It is particularly not permitted to make changes in response to a call to the `ListModel` consumer API. Stated another way: in general, it is assumed that code making a series of accesses to the model via the API, without returning to the mainloop, and without calling other code, will continue to view the same contents of the model. Feature: `v2_44` ## `position` the position at which `self` changed ## `removed` the number of items removed ## `added` the number of items added This signal is emitted whenever items were added or removed to `list`. At `position`, `removed` items were removed and `added` items were added in their place. Feature: `v2_44` ## `position` the position at which `list` changed ## `removed` the number of items removed ## `added` the number of items added `ListStore` is a simple implementation of `ListModel` that stores all items in memory. It provides insertions, deletions, and lookups in logarithmic time with a fast path for the common case of iterating the list linearly. Feature: `v2_44` # Implements [`ListStoreExt`](trait.ListStoreExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ListModelExt`](trait.ListModelExt.html), [`ListStoreExtManual`](prelude/trait.ListStoreExtManual.html) Trait containing all `ListStore` methods. Feature: `v2_44` # Implementors [`ListStore`](struct.ListStore.html) Creates a new `ListStore` with items of type `item_type`. `item_type` must be a subclass of `gobject::Object`. Feature: `v2_44` ## `item_type` the `glib::Type` of items in the list # Returns a new `ListStore` Appends `item` to `self`. `item` must be of type `ListStore:item-type`. This function takes a ref on `item`. Use `ListStoreExt::splice` to append multiple items at the same time efficiently. Feature: `v2_44` ## `item` the new item Inserts `item` into `self` at `position`. `item` must be of type `ListStore:item-type` or derived from it. `position` must be smaller than the length of the list, or equal to it to append. This function takes a ref on `item`. Use `ListStoreExt::splice` to insert multiple items at the same time efficiently. Feature: `v2_44` ## `position` the position at which to insert the new item ## `item` the new item Inserts `item` into `self` at a position to be determined by the `compare_func`. The list must already be sorted before calling this function or the result is undefined. Usually you would approach this by only ever inserting items by way of this function. This function takes a ref on `item`. Feature: `v2_44` ## `item` the new item ## `compare_func` pairwise comparison function for sorting ## `user_data` user data for `compare_func` # Returns the position at which `item` was inserted Removes the item from `self` that is at `position`. `position` must be smaller than the current length of the list. Use `ListStoreExt::splice` to remove multiple items at the same time efficiently. Feature: `v2_44` ## `position` the position of the item that is to be removed Removes all items from `self`. Feature: `v2_44` Sort the items in `self` according to `compare_func`. Feature: `v2_46` ## `compare_func` pairwise comparison function for sorting ## `user_data` user data for `compare_func` Changes `self` by removing `n_removals` items and adding `n_additions` items to it. `additions` must contain `n_additions` items of type `ListStore:item-type`. `None` is not permitted. This function is more efficient than `ListStoreExt::insert` and `ListStoreExt::remove`, because it only emits `ListModel::items-changed` once for the change. This function takes a ref on each item in `additions`. The parameters `position` and `n_removals` must be correct (ie: `position` + `n_removals` must be less than or equal to the length of the list at the time this function is called). Feature: `v2_44` ## `position` the position at which to make the change ## `n_removals` the number of items to remove ## `additions` the items to add ## `n_additions` the number of items to add The type of items contained in this list store. Items must be subclasses of `gobject::Object`. Feature: `v2_44` The type of items contained in this list store. Items must be subclasses of `gobject::Object`. Feature: `v2_44` Extends the `Icon` interface and adds the ability to load icons from streams. # Implements [`LoadableIconExt`](trait.LoadableIconExt.html), [`IconExt`](trait.IconExt.html) Trait containing all `LoadableIcon` methods. # Implementors [`BytesIcon`](struct.BytesIcon.html), [`FileIcon`](struct.FileIcon.html), [`LoadableIcon`](struct.LoadableIcon.html) Loads a loadable icon. For the asynchronous version of this function, see `LoadableIcon::load_async`. ## `size` an integer. ## `type_` a location to store the type of the loaded icon, `None` to ignore. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `InputStream` to read the icon from. Loads an icon asynchronously. To finish this function, see `LoadableIcon::load_finish`. For the synchronous, blocking version of this function, see `LoadableIcon::load`. ## `size` an integer. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous icon load started in `LoadableIcon::load_async`. ## `res` a `AsyncResult`. ## `type_` a location to store the type of the loaded icon, `None` to ignore. # Returns a `InputStream` to read the icon from. `MemoryInputStream` is a class for using arbitrary memory chunks as input for GIO streaming input operations. As of GLib 2.34, `MemoryInputStream` implements `PollableInputStream`. # Implements [`MemoryInputStreamExt`](trait.MemoryInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableInputStreamExt`](trait.PollableInputStreamExt.html), [`SeekableExt`](trait.SeekableExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html), [`PollableInputStreamExtManual`](prelude/trait.PollableInputStreamExtManual.html) Trait containing all `MemoryInputStream` methods. # Implementors [`MemoryInputStream`](struct.MemoryInputStream.html) Creates a new empty `MemoryInputStream`. # Returns a new `InputStream` Creates a new `MemoryInputStream` with data from the given `bytes`. ## `bytes` a `glib::Bytes` # Returns new `InputStream` read from `bytes` Creates a new `MemoryInputStream` with data in memory of a given size. ## `data` input data ## `len` length of the data, may be -1 if `data` is a nul-terminated string ## `destroy` function that is called to free `data`, or `None` # Returns new `InputStream` read from `data` of `len` bytes. Appends `bytes` to data that can be read from the input stream. ## `bytes` input data Appends `data` to data that can be read from the input stream ## `data` input data ## `len` length of the data, may be -1 if `data` is a nul-terminated string ## `destroy` function that is called to free `data`, or `None` `MemoryOutputStream` is a class for using arbitrary memory chunks as output for GIO streaming output operations. As of GLib 2.34, `MemoryOutputStream` trivially implements `PollableOutputStream`: it always polls as ready. # Implements [`MemoryOutputStreamExt`](trait.MemoryOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableOutputStreamExt`](trait.PollableOutputStreamExt.html), [`SeekableExt`](trait.SeekableExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html), [`PollableOutputStreamExtManual`](prelude/trait.PollableOutputStreamExtManual.html) Trait containing all `MemoryOutputStream` methods. # Implementors [`MemoryOutputStream`](struct.MemoryOutputStream.html) Creates a new `MemoryOutputStream`. In most cases this is not the function you want. See `MemoryOutputStream::new_resizable` instead. If `data` is non-`None`, the stream will use that for its internal storage. If `realloc_fn` is non-`None`, it will be used for resizing the internal storage when necessary and the stream will be considered resizable. In that case, the stream will start out being (conceptually) empty. `size` is used only as a hint for how big `data` is. Specifically, seeking to the end of a newly-created stream will seek to zero, not `size`. Seeking past the end of the stream and then writing will introduce a zero-filled gap. If `realloc_fn` is `None` then the stream is fixed-sized. Seeking to the end will seek to `size` exactly. Writing past the end will give an 'out of space' error. Attempting to seek past the end will fail. Unlike the resizable case, seeking to an offset within the stream and writing will preserve the bytes passed in as `data` before that point and will return them as part of `MemoryOutputStream::steal_data`. If you intend to seek you should probably therefore ensure that `data` is properly initialised. It is probably only meaningful to provide `data` and `size` in the case that you want a fixed-sized stream. Put another way: if `realloc_fn` is non-`None` then it makes most sense to give `data` as `None` and `size` as 0 (allowing `MemoryOutputStream` to do the initial allocation for itself). ```C // a stream that can grow stream = g_memory_output_stream_new (NULL, 0, realloc, free); // another stream that can grow stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); // a fixed-size stream data = malloc (200); stream3 = g_memory_output_stream_new (data, 200, NULL, free); ``` ## `data` pointer to a chunk of memory to use, or `None` ## `size` the size of `data` ## `realloc_function` a function with `realloc` semantics (like `g_realloc`) to be called when `data` needs to be grown, or `None` ## `destroy_function` a function to be called on `data` when the stream is finalized, or `None` # Returns A newly created `MemoryOutputStream` object. Creates a new `MemoryOutputStream`, using `g_realloc` and `g_free` for memory allocation. Gets any loaded data from the `self`. Note that the returned pointer may become invalid on the next write or truncate operation on the stream. # Returns pointer to the stream's data, or `None` if the data has been stolen Returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away. # Returns the number of bytes written to the stream Gets the size of the currently allocated data area (available from `MemoryOutputStream::get_data`). You probably don't want to use this function on resizable streams. See `MemoryOutputStreamExt::get_data_size` instead. For resizable streams the size returned by this function is an implementation detail and may be change at any time in response to operations on the stream. If the stream is fixed-sized (ie: no realloc was passed to `MemoryOutputStream::new`) then this is the maximum size of the stream and further writes will return `IOErrorEnum::NoSpace`. In any case, if you want the number of bytes currently written to the stream, use `MemoryOutputStreamExt::get_data_size`. # Returns the number of bytes allocated for the data buffer Returns data from the `self` as a `glib::Bytes`. `self` must be closed before calling this function. # Returns the stream's data Gets any loaded data from the `self`. Ownership of the data is transferred to the caller; when no longer needed it must be freed using the free function set in `self`'s `MemoryOutputStream:destroy-function` property. `self` must be closed before calling this function. # Returns the stream's data, or `None` if it has previously been stolen Pointer to buffer where data will be written. Pointer to buffer where data will be written. Size of data written to the buffer. Function called with the buffer as argument when the stream is destroyed. Function called with the buffer as argument when the stream is destroyed. Function with realloc semantics called to enlarge the buffer. Function with realloc semantics called to enlarge the buffer. Current size of the data buffer. Current size of the data buffer. `Menu` is a simple implementation of `MenuModel`. You populate a `Menu` by adding `MenuItem` instances to it. There are some convenience functions to allow you to directly add items (avoiding `MenuItem`) for the common cases. To add a regular item, use `Menu::insert`. To add a section, use `Menu::insert_section`. To add a submenu, use `Menu::insert_submenu`. # Implements [`MenuModelExt`](trait.MenuModelExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Menu`. The new menu has no items. # Returns a new `Menu` Convenience function for appending a normal menu item to the end of `self`. Combine `MenuItem::new` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `detailed_action` the detailed action string, or `None` Appends `item` to the end of `self`. See `Menu::insert_item` for more information. ## `item` a `MenuItem` to append Convenience function for appending a section menu item to the end of `self`. Combine `MenuItem::new_section` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `section` a `MenuModel` with the items of the section Convenience function for appending a submenu menu item to the end of `self`. Combine `MenuItem::new_submenu` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `submenu` a `MenuModel` with the items of the submenu Marks `self` as frozen. After the menu is frozen, it is an error to attempt to make any changes to it. In effect this means that the `Menu` API must no longer be used. This function causes `MenuModelExt::is_mutable` to begin returning `false`, which has some positive performance implications. Convenience function for inserting a normal menu item into `self`. Combine `MenuItem::new` and `Menu::insert_item` for a more flexible alternative. ## `position` the position at which to insert the item ## `label` the section label, or `None` ## `detailed_action` the detailed action string, or `None` Inserts `item` into `self`. The "insertion" is actually done by copying all of the attribute and link values of `item` and using them to form a new item within `self`. As such, `item` itself is not really inserted, but rather, a menu item that is exactly the same as the one presently described by `item`. This means that `item` is essentially useless after the insertion occurs. Any changes you make to it are ignored unless it is inserted again (at which point its updated values will be copied). You should probably just free `item` once you're done. There are many convenience functions to take care of common cases. See `Menu::insert`, `Menu::insert_section` and `Menu::insert_submenu` as well as "prepend" and "append" variants of each of these functions. ## `position` the position at which to insert the item ## `item` the `MenuItem` to insert Convenience function for inserting a section menu item into `self`. Combine `MenuItem::new_section` and `Menu::insert_item` for a more flexible alternative. ## `position` the position at which to insert the item ## `label` the section label, or `None` ## `section` a `MenuModel` with the items of the section Convenience function for inserting a submenu menu item into `self`. Combine `MenuItem::new_submenu` and `Menu::insert_item` for a more flexible alternative. ## `position` the position at which to insert the item ## `label` the section label, or `None` ## `submenu` a `MenuModel` with the items of the submenu Convenience function for prepending a normal menu item to the start of `self`. Combine `MenuItem::new` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `detailed_action` the detailed action string, or `None` Prepends `item` to the start of `self`. See `Menu::insert_item` for more information. ## `item` a `MenuItem` to prepend Convenience function for prepending a section menu item to the start of `self`. Combine `MenuItem::new_section` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `section` a `MenuModel` with the items of the section Convenience function for prepending a submenu menu item to the start of `self`. Combine `MenuItem::new_submenu` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `submenu` a `MenuModel` with the items of the submenu Removes an item from the menu. `position` gives the index of the item to remove. It is an error if position is not in range the range from 0 to one less than the number of items in the menu. It is not possible to remove items by identity since items are added to the menu simply by copying their links and attributes (ie: identity of the item itself is not preserved). ## `position` the position of the item to remove Removes all items in the menu. `MenuAttributeIter` is an opaque structure type. You must access it using the functions below. # Implements [`MenuAttributeIterExt`](trait.MenuAttributeIterExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `MenuAttributeIter` methods. # Implementors [`MenuAttributeIter`](struct.MenuAttributeIter.html) Gets the name of the attribute at the current iterator position, as a string. The iterator is not advanced. # Returns the name of the attribute This function combines `MenuAttributeIterExt::next` with `MenuAttributeIterExt::get_name` and `MenuAttributeIterExt::get_value`. First the iterator is advanced to the next (possibly first) attribute. If that fails, then `false` is returned and there are no other effects. If successful, `name` and `value` are set to the name and value of the attribute that has just been advanced to. At this point, `MenuAttributeIterExt::get_name` and `MenuAttributeIterExt::get_value` will return the same values again. The value returned in `name` remains valid for as long as the iterator remains at the current position. The value returned in `value` must be unreffed using `glib::Variant::unref` when it is no longer in use. ## `out_name` the type of the attribute ## `value` the attribute value # Returns `true` on success, or `false` if there is no additional attribute Gets the value of the attribute at the current iterator position. The iterator is not advanced. # Returns the value of the current attribute Attempts to advance the iterator to the next (possibly first) attribute. `true` is returned on success, or `false` if there are no more attributes. You must call this function when you first acquire the iterator to advance it to the first attribute (and determine if the first attribute exists at all). # Returns `true` on success, or `false` when there are no more attributes `MenuItem` is an opaque structure type. You must access it using the functions below. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `MenuItem`. If `label` is non-`None` it is used to set the "label" attribute of the new item. If `detailed_action` is non-`None` it is used to set the "action" and possibly the "target" attribute of the new item. See `MenuItem::set_detailed_action` for more information. ## `label` the section label, or `None` ## `detailed_action` the detailed action string, or `None` # Returns a new `MenuItem` Creates a `MenuItem` as an exact copy of an existing menu item in a `MenuModel`. `item_index` must be valid (ie: be sure to call `MenuModelExt::get_n_items` first). ## `model` a `MenuModel` ## `item_index` the index of an item in `model` # Returns a new `MenuItem`. Creates a new `MenuItem` representing a section. This is a convenience API around `MenuItem::new` and `MenuItem::set_section`. The effect of having one menu appear as a section of another is exactly as it sounds: the items from `section` become a direct part of the menu that `menu_item` is added to. Visual separation is typically displayed between two non-empty sections. If `label` is non-`None` then it will be encorporated into this visual indication. This allows for labeled subsections of a menu. As a simple example, consider a typical "Edit" menu from a simple program. It probably contains an "Undo" and "Redo" item, followed by a separator, followed by "Cut", "Copy" and "Paste". This would be accomplished by creating three `Menu` instances. The first would be populated with the "Undo" and "Redo" items, and the second with the "Cut", "Copy" and "Paste" items. The first and second menus would then be added as submenus of the third. In XML format, this would look something like the following: ```text
``` The following example is exactly equivalent. It is more illustrative of the exact relationship between the menus and items (keeping in mind that the 'link' element defines a new menu that is linked to the containing one). The style of the second example is more verbose and difficult to read (and therefore not recommended except for the purpose of understanding what is really going on). ```text ``` ## `label` the section label, or `None` ## `section` a `MenuModel` with the items of the section # Returns a new `MenuItem` Creates a new `MenuItem` representing a submenu. This is a convenience API around `MenuItem::new` and `MenuItem::set_submenu`. ## `label` the section label, or `None` ## `submenu` a `MenuModel` with the items of the submenu # Returns a new `MenuItem` Queries the named `attribute` on `self`. If the attribute exists and matches the `glib::VariantType` corresponding to `format_string` then `format_string` is used to deconstruct the value into the positional parameters and `true` is returned. If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and `false` is returned. ## `attribute` the attribute name to query ## `format_string` a `glib::Variant` format string # Returns `true` if the named attribute was found with the expected type Queries the named `attribute` on `self`. If `expected_type` is specified and the attribute does not have this type, `None` is returned. `None` is also returned if the attribute simply does not exist. ## `attribute` the attribute name to query ## `expected_type` the expected type of the attribute # Returns the attribute value, or `None` Queries the named `link` on `self`. ## `link` the link name to query # Returns the link, or `None` Sets or unsets the "action" and "target" attributes of `self`. If `action` is `None` then both the "action" and "target" attributes are unset (and `format_string` is ignored along with the positional parameters). If `action` is non-`None` then the "action" attribute is set. `format_string` is then inspected. If it is non-`None` then the proper position parameters are collected to create a `glib::Variant` instance to use as the target value. If it is `None` then the positional parameters are ignored and the "target" attribute is unset. See also `MenuItem::set_action_and_target_value` for an equivalent call that directly accepts a `glib::Variant`. See `MenuItem::set_detailed_action` for a more convenient version that works with string-typed targets. See also `MenuItem::set_action_and_target_value` for a description of the semantics of the action and target attributes. ## `action` the name of the action for this item ## `format_string` a GVariant format string Sets or unsets the "action" and "target" attributes of `self`. If `action` is `None` then both the "action" and "target" attributes are unset (and `target_value` is ignored). If `action` is non-`None` then the "action" attribute is set. The "target" attribute is then set to the value of `target_value` if it is non-`None` or unset otherwise. Normal menu items (ie: not submenu, section or other custom item types) are expected to have the "action" attribute set to identify the action that they are associated with. The state type of the action help to determine the disposition of the menu item. See `Action` and `ActionGroup` for an overview of actions. In general, clicking on the menu item will result in activation of the named action with the "target" attribute given as the parameter to the action invocation. If the "target" attribute is not set then the action is invoked with no parameter. If the action has no state then the menu item is usually drawn as a plain menu item (ie: with no additional decoration). If the action has a boolean state then the menu item is usually drawn as a toggle menu item (ie: with a checkmark or equivalent indication). The item should be marked as 'toggled' or 'checked' when the boolean state is `true`. If the action has a string state then the menu item is usually drawn as a radio menu item (ie: with a radio bullet or equivalent indication). The item should be marked as 'selected' when the string state is equal to the value of the `target` property. See `MenuItem::set_action_and_target` or `MenuItem::set_detailed_action` for two equivalent calls that are probably more convenient for most uses. ## `action` the name of the action for this item ## `target_value` a `glib::Variant` to use as the action target Sets or unsets an attribute on `self`. The attribute to set or unset is specified by `attribute`. This can be one of the standard attribute names `G_MENU_ATTRIBUTE_LABEL`, `G_MENU_ATTRIBUTE_ACTION`, `G_MENU_ATTRIBUTE_TARGET`, or a custom attribute name. Attribute names are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes. If `format_string` is non-`None` then the proper position parameters are collected to create a `glib::Variant` instance to use as the attribute value. If it is `None` then the positional parameterrs are ignored and the named attribute is unset. See also `MenuItem::set_attribute_value` for an equivalent call that directly accepts a `glib::Variant`. ## `attribute` the attribute to set ## `format_string` a `glib::Variant` format string, or `None` Sets or unsets an attribute on `self`. The attribute to set or unset is specified by `attribute`. This can be one of the standard attribute names `G_MENU_ATTRIBUTE_LABEL`, `G_MENU_ATTRIBUTE_ACTION`, `G_MENU_ATTRIBUTE_TARGET`, or a custom attribute name. Attribute names are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes. must consist only of lowercase ASCII characters, digits and '-'. If `value` is non-`None` then it is used as the new value for the attribute. If `value` is `None` then the attribute is unset. If the `value` `glib::Variant` is floating, it is consumed. See also `MenuItem::set_attribute` for a more convenient way to do the same. ## `attribute` the attribute to set ## `value` a `glib::Variant` to use as the value, or `None` Sets the "action" and possibly the "target" attribute of `self`. The format of `detailed_action` is the same format parsed by `Action::parse_detailed_name`. See `MenuItem::set_action_and_target` or `MenuItem::set_action_and_target_value` for more flexible (but slightly less convenient) alternatives. See also `MenuItem::set_action_and_target_value` for a description of the semantics of the action and target attributes. ## `detailed_action` the "detailed" action string Sets (or unsets) the icon on `self`. This call is the same as calling `Icon::serialize` and using the result as the value to `MenuItem::set_attribute_value` for `G_MENU_ATTRIBUTE_ICON`. This API is only intended for use with "noun" menu items; things like bookmarks or applications in an "Open With" menu. Don't use it on menu items corresponding to verbs (eg: stock icons for 'Save' or 'Quit'). If `icon` is `None` then the icon is unset. ## `icon` a `Icon`, or `None` Sets or unsets the "label" attribute of `self`. If `label` is non-`None` it is used as the label for the menu item. If it is `None` then the label attribute is unset. ## `label` the label to set, or `None` to unset Creates a link from `self` to `model` if non-`None`, or unsets it. Links are used to establish a relationship between a particular menu item and another menu. For example, `G_MENU_LINK_SUBMENU` is used to associate a submenu with a particular menu item, and `G_MENU_LINK_SECTION` is used to create a section. Other types of link can be used, but there is no guarantee that clients will be able to make sense of them. Link types are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes. ## `link` type of link to establish or unset ## `model` the `MenuModel` to link to (or `None` to unset) Sets or unsets the "section" link of `self` to `section`. The effect of having one menu appear as a section of another is exactly as it sounds: the items from `section` become a direct part of the menu that `self` is added to. See `MenuItem::new_section` for more information about what it means for a menu item to be a section. ## `section` a `MenuModel`, or `None` Sets or unsets the "submenu" link of `self` to `submenu`. If `submenu` is non-`None`, it is linked to. If it is `None` then the link is unset. The effect of having one menu appear as a submenu of another is exactly as it sounds. ## `submenu` a `MenuModel`, or `None` `MenuLinkIter` is an opaque structure type. You must access it using the functions below. # Implements [`MenuLinkIterExt`](trait.MenuLinkIterExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `MenuLinkIter` methods. # Implementors [`MenuLinkIter`](struct.MenuLinkIter.html) Gets the name of the link at the current iterator position. The iterator is not advanced. # Returns the type of the link This function combines `MenuLinkIterExt::next` with `MenuLinkIterExt::get_name` and `MenuLinkIterExt::get_value`. First the iterator is advanced to the next (possibly first) link. If that fails, then `false` is returned and there are no other effects. If successful, `out_link` and `value` are set to the name and `MenuModel` of the link that has just been advanced to. At this point, `MenuLinkIterExt::get_name` and `MenuLinkIterExt::get_value` will return the same values again. The value returned in `out_link` remains valid for as long as the iterator remains at the current position. The value returned in `value` must be unreffed using `gobject::ObjectExt::unref` when it is no longer in use. ## `out_link` the name of the link ## `value` the linked `MenuModel` # Returns `true` on success, or `false` if there is no additional link Gets the linked `MenuModel` at the current iterator position. The iterator is not advanced. # Returns the `MenuModel` that is linked to Attempts to advance the iterator to the next (possibly first) link. `true` is returned on success, or `false` if there are no more links. You must call this function when you first acquire the iterator to advance it to the first link (and determine if the first link exists at all). # Returns `true` on success, or `false` when there are no more links `MenuModel` represents the contents of a menu -- an ordered list of menu items. The items are associated with actions, which can be activated through them. Items can be grouped in sections, and may have submenus associated with them. Both items and sections usually have some representation data, such as labels or icons. The type of the associated action (ie whether it is stateful, and what kind of state it has) can influence the representation of the item. The conceptual model of menus in `MenuModel` is hierarchical: sections and submenus are again represented by `GMenuModels`. Menus themselves do not define their own roles. Rather, the role of a particular `MenuModel` is defined by the item that references it (or, in the case of the 'root' menu, is defined by the context in which it is used). As an example, consider the visible portions of this menu: ## An example menu # {`menu`-example} ![](menu-example.png) There are 8 "menus" visible in the screenshot: one menubar, two submenus and 5 sections: - the toplevel menubar (containing 4 items) - the View submenu (containing 3 sections) - the first section of the View submenu (containing 2 items) - the second section of the View submenu (containing 1 item) - the final section of the View submenu (containing 1 item) - the Highlight Mode submenu (containing 2 sections) - the Sources section (containing 2 items) - the Markup section (containing 2 items) The [example][menu-model] illustrates the conceptual connection between these 8 menus. Each large block in the figure represents a menu and the smaller blocks within the large block represent items in that menu. Some items contain references to other menus. ## A menu example # {`menu`-model} ![](menu-model.png) Notice that the separators visible in the [example][menu-example] appear nowhere in the [menu model][menu-model]. This is because separators are not explicitly represented in the menu model. Instead, a separator is inserted between any two non-empty sections of a menu. Section items can have labels just like any other item. In that case, a display system may show a section header instead of a separator. The motivation for this abstract model of application controls is that modern user interfaces tend to make these controls available outside the application. Examples include global menus, jumplists, dash boards, etc. To support such uses, it is necessary to 'export' information about actions and their representation in menus, which is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] and the [GMenuModel exporter][gio-GMenuModel-exporter] do for `ActionGroup` and `MenuModel`. The client-side counterparts to make use of the exported information are `DBusActionGroup` and `DBusMenuModel`. The API of `MenuModel` is very generic, with iterators for the attributes and links of an item, see `MenuModelExt::iterate_item_attributes` and `MenuModelExt::iterate_item_links`. The 'standard' attributes and link types have predefined names: `G_MENU_ATTRIBUTE_LABEL`, `G_MENU_ATTRIBUTE_ACTION`, `G_MENU_ATTRIBUTE_TARGET`, `G_MENU_LINK_SECTION` and `G_MENU_LINK_SUBMENU`. Items in a `MenuModel` represent active controls if they refer to an action that can get activated when the user interacts with the menu item. The reference to the action is encoded by the string id in the `G_MENU_ATTRIBUTE_ACTION` attribute. An action id uniquely identifies an action in an action group. Which action group(s) provide actions depends on the context in which the menu model is used. E.g. when the model is exported as the application menu of a ``GtkApplication``, actions can be application-wide or window-specific (and thus come from two different action groups). By convention, the application-wide actions have names that start with "app.", while the names of window-specific actions start with "win.". While a wide variety of stateful actions is possible, the following is the minimum that is expected to be supported by all users of exported menu information: - an action with no parameter type and no state - an action with no parameter type and boolean state - an action with string parameter type and string state ## Stateless A stateless action typically corresponds to an ordinary menu item. Selecting such a menu item will activate the action (with no parameter). ## Boolean State An action with a boolean state will most typically be used with a "toggle" or "switch" menu item. The state can be set directly, but activating the action (with no parameter) results in the state being toggled. Selecting a toggle menu item will activate the action. The menu item should be rendered as "checked" when the state is true. ## String Parameter and State Actions with string parameters and state will most typically be used to represent an enumerated choice over the items available for a group of radio menu items. Activating the action with a string parameter is equivalent to setting that parameter as the state. Radio menu items, in addition to being associated with the action, will have a target value. Selecting that menu item will result in activation of the action with the target value as the parameter. The menu item should be rendered as "selected" when the state of the action is equal to the target value of the menu item. # Implements [`MenuModelExt`](trait.MenuModelExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `MenuModel` methods. # Implementors [`MenuModel`](struct.MenuModel.html), [`Menu`](struct.Menu.html) Queries item at position `item_index` in `self` for the attribute specified by `attribute`. If the attribute exists and matches the `glib::VariantType` corresponding to `format_string` then `format_string` is used to deconstruct the value into the positional parameters and `true` is returned. If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and `false` is returned. This function is a mix of `MenuModelExt::get_item_attribute_value` and `glib::Variant::get`, followed by a `glib::Variant::unref`. As such, `format_string` must make a complete copy of the data (since the `glib::Variant` may go away after the call to `glib::Variant::unref`). In particular, no '&' characters are allowed in `format_string`. ## `item_index` the index of the item ## `attribute` the attribute to query ## `format_string` a `glib::Variant` format string # Returns `true` if the named attribute was found with the expected type Queries the item at position `item_index` in `self` for the attribute specified by `attribute`. If `expected_type` is non-`None` then it specifies the expected type of the attribute. If it is `None` then any type will be accepted. If the attribute exists and matches `expected_type` (or if the expected type is unspecified) then the value is returned. If the attribute does not exist, or does not match the expected type then `None` is returned. ## `item_index` the index of the item ## `attribute` the attribute to query ## `expected_type` the expected type of the attribute, or `None` # Returns the value of the attribute Queries the item at position `item_index` in `self` for the link specified by `link`. If the link exists, the linked `MenuModel` is returned. If the link does not exist, `None` is returned. ## `item_index` the index of the item ## `link` the link to query # Returns the linked `MenuModel`, or `None` Query the number of items in `self`. # Returns the number of items Queries if `self` is mutable. An immutable `MenuModel` will never emit the `MenuModel::items-changed` signal. Consumers of the model may make optimisations accordingly. # Returns `true` if the model is mutable (ie: "items-changed" may be emitted). Requests emission of the `MenuModel::items-changed` signal on `self`. This function should never be called except by `MenuModel` subclasses. Any other calls to this function will very likely lead to a violation of the interface of the model. The implementation should update its internal representation of the menu before emitting the signal. The implementation should further expect to receive queries about the new state of the menu (and particularly added menu items) while signal handlers are running. The implementation must dispatch this call directly from a mainloop entry and not in response to calls -- particularly those from the `MenuModel` API. Said another way: the menu must not change while user code is running without returning to the mainloop. ## `position` the position of the change ## `removed` the number of items removed ## `added` the number of items added Creates a `MenuAttributeIter` to iterate over the attributes of the item at position `item_index` in `self`. You must free the iterator with `gobject::ObjectExt::unref` when you are done. ## `item_index` the index of the item # Returns a new `MenuAttributeIter` Creates a `MenuLinkIter` to iterate over the links of the item at position `item_index` in `self`. You must free the iterator with `gobject::ObjectExt::unref` when you are done. ## `item_index` the index of the item # Returns a new `MenuLinkIter` Emitted when a change has occured to the menu. The only changes that can occur to a menu is that items are removed or added. Items may not change (except by being removed and added back in the same location). This signal is capable of describing both of those changes (at the same time). The signal means that starting at the index `position`, `removed` items were removed and `added` items were added in their place. If `removed` is zero then only items were added. If `added` is zero then only items were removed. As an example, if the menu contains items a, b, c, d (in that order) and the signal (2, 1, 3) occurs then the new composition of the menu will be a, b, _, _, _, d (with each _ representing some new item). Signal handlers may query the model (particularly the added items) and expect to see the results of the modification that is being reported. The signal is emitted after the modification. ## `position` the position of the change ## `removed` the number of items removed ## `added` the number of items added The `Mount` interface represents user-visible mounts. Note, when porting from GnomeVFS, `Mount` is the moral equivalent of `GnomeVFSVolume`. `Mount` is a "mounted" filesystem that you can access. Mounted is in quotes because it's not the same as a unix mount, it might be a gvfs mount, but you can still access the files on it if you use GIO. Might or might not be related to a volume object. Unmounting a `Mount` instance is an asynchronous operation. For more information about asynchronous operations, see `AsyncResult` and `Task`. To unmount a `Mount` instance, first call `Mount::unmount_with_operation` with (at least) the `Mount` instance and a `GAsyncReadyCallback`. The callback will be fired when the operation has resolved (either with success or failure), and a `AsyncResult` structure will be passed to the callback. That callback should then call `Mount::unmount_with_operation_finish` with the `Mount` and the `AsyncResult` data to see if the operation was completed successfully. If an `error` is present when `Mount::unmount_with_operation_finish` is called, then it will be filled with any error information. # Implements [`MountExt`](trait.MountExt.html) Trait containing all `Mount` methods. # Implementors [`Mount`](struct.Mount.html) Checks if `self` can be ejected. # Returns `true` if the `self` can be ejected. Checks if `self` can be unmounted. # Returns `true` if the `self` can be unmounted. Ejects a mount. This is an asynchronous operation, and is finished by calling `Mount::eject_with_operation_finish` with the `self` and `AsyncResult` data returned in the `callback`. ## `flags` flags affecting the unmount if required for eject ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data passed to `callback`. Finishes ejecting a mount. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. ## `result` a `AsyncResult`. # Returns `true` if the mount was successfully ejected. `false` otherwise. Gets the default location of `self`. The default location of the given `self` is a path that reflects the main entry point for the user (e.g. the home directory, or the root of the volume). # Returns a `File`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the drive for the `self`. This is a convenience method for getting the `Volume` and then using that object to get the `Drive`. # Returns a `Drive` or `None` if `self` is not associated with a volume or a drive. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the icon for `self`. # Returns a `Icon`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the name of `self`. # Returns the name for the given `self`. The returned string should be freed with `g_free` when no longer needed. Gets the root directory on `self`. # Returns a `File`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the sort key for `self`, if any. # Returns Sorting key for `self` or `None` if no such key is available. Gets the symbolic icon for `self`. # Returns a `Icon`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the UUID for the `self`. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns `None` if there is no UUID available. # Returns the UUID for `self` or `None` if no UUID can be computed. The returned string should be freed with `g_free` when no longer needed. Gets the volume for the `self`. # Returns a `Volume` or `None` if `self` is not associated with a volume. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Tries to guess the type of content stored on `self`. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types. This is an asynchronous operation (see `Mount::guess_content_type_sync` for the synchronous version), and is finished by calling `Mount::guess_content_type_finish` with the `self` and `AsyncResult` data returned in the `callback`. ## `force_rescan` Whether to force a rescan of the content. Otherwise a cached result will be used if available ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` ## `user_data` user data passed to `callback` Finishes guessing content types of `self`. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. In particular, you may get an `IOErrorEnum::NotSupported` if the mount does not support content guessing. ## `result` a `AsyncResult` # Returns a `None`-terminated array of content types or `None` on error. Caller should free this array with `g_strfreev` when done with it. Tries to guess the type of content stored on `self`. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types. This is an synchronous operation and as such may block doing IO; see `Mount::guess_content_type` for the asynchronous version. ## `force_rescan` Whether to force a rescan of the content. Otherwise a cached result will be used if available ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `None`-terminated array of content types or `None` on error. Caller should free this array with `g_strfreev` when done with it. Determines if `self` is shadowed. Applications or libraries should avoid displaying `self` in the user interface if it is shadowed. A mount is said to be shadowed if there exists one or more user visible objects (currently `Mount` objects) with a root that is inside the root of `self`. One application of shadow mounts is when exposing a single file system that is used to address several logical volumes. In this situation, a `VolumeMonitor` implementation would create two `Volume` objects (for example, one for the camera functionality of the device and one for a SD card reader on the device) with activation URIs `gphoto2://[usb:001,002]/store1/` and `gphoto2://[usb:001,002]/store2/`. When the underlying mount (with root `gphoto2://[usb:001,002]/`) is mounted, said `VolumeMonitor` implementation would create two `Mount` objects (each with their root matching the corresponding volume activation root) that would shadow the original mount. The proxy monitor in GVfs 2.26 and later, automatically creates and manage shadow mounts (and shadows the underlying mount) if the activation root on a `Volume` is set. # Returns `true` if `self` is shadowed. Remounts a mount. This is an asynchronous operation, and is finished by calling `Mount::remount_finish` with the `self` and `GAsyncResults` data returned in the `callback`. Remounting is useful when some setting affecting the operation of the volume has been changed, as these may need a remount to take affect. While this is semantically equivalent with unmounting and then remounting not all backends might need to actually be unmounted. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data passed to `callback`. Finishes remounting a mount. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. ## `result` a `AsyncResult`. # Returns `true` if the mount was successfully remounted. `false` otherwise. Increments the shadow count on `self`. Usually used by `VolumeMonitor` implementations when creating a shadow mount for `self`, see `Mount::is_shadowed` for more information. The caller will need to emit the `Mount::changed` signal on `self` manually. Unmounts a mount. This is an asynchronous operation, and is finished by calling `Mount::unmount_with_operation_finish` with the `self` and `AsyncResult` data returned in the `callback`. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data passed to `callback`. Finishes unmounting a mount. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. ## `result` a `AsyncResult`. # Returns `true` if the mount was successfully unmounted. `false` otherwise. Decrements the shadow count on `self`. Usually used by `VolumeMonitor` implementations when destroying a shadow mount for `self`, see `Mount::is_shadowed` for more information. The caller will need to emit the `Mount::changed` signal on `self` manually. Emitted when the mount has been changed. This signal may be emitted when the `Mount` is about to be unmounted. This signal depends on the backend and is only emitted if GIO was used to unmount. This signal is emitted when the `Mount` have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. `MountOperation` provides a mechanism for interacting with the user. It can be used for authenticating mountable operations, such as loop mounting files, hard drive partitions or server locations. It can also be used to ask the user questions or show a list of applications preventing unmount or eject operations from completing. Note that `MountOperation` is used for more than just `Mount` objects – for example it is also used in `Drive::start` and `Drive::stop`. Users should instantiate a subclass of this that implements all the various callbacks to show the required dialogs, such as ``GtkMountOperation``. If no user interaction is desired (for example when automounting filesystems at login time), usually `None` can be passed, see each method taking a `MountOperation` for details. The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. [TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for encrypting file containers, partitions or whole disks, typically used with Windows. [VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various improvements and auditing fixes. # Implements [`MountOperationExt`](trait.MountOperationExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `MountOperation` methods. # Implementors [`MountOperation`](struct.MountOperation.html) Creates a new mount operation. # Returns a `MountOperation`. Check to see whether the mount operation is being used for an anonymous user. # Returns `true` if mount operation is anonymous. Gets a choice from the mount operation. # Returns an integer containing an index of the user's choice from the choice's list, or `0`. Gets the domain of the mount operation. # Returns a string set to the domain. Check to see whether the mount operation is being used for a TCRYPT hidden volume. Feature: `v2_58` # Returns `true` if mount operation is for hidden volume. Check to see whether the mount operation is being used for a TCRYPT system volume. Feature: `v2_58` # Returns `true` if mount operation is for system volume. Gets a password from the mount operation. # Returns a string containing the password within `self`. Gets the state of saving passwords for the mount operation. # Returns a `PasswordSave` flag. Gets a PIM from the mount operation. Feature: `v2_58` # Returns The VeraCrypt PIM within `self`. Get the user name from the mount operation. # Returns a string containing the user name. Emits the `MountOperation::reply` signal. ## `result` a `MountOperationResult` Sets the mount operation to use an anonymous user if `anonymous` is `true`. ## `anonymous` boolean value. Sets a default choice for the mount operation. ## `choice` an integer. Sets the mount operation's domain. ## `domain` the domain to set. Sets the mount operation to use a hidden volume if `hidden_volume` is `true`. Feature: `v2_58` ## `hidden_volume` boolean value. Sets the mount operation to use a system volume if `system_volume` is `true`. Feature: `v2_58` ## `system_volume` boolean value. Sets the mount operation's password to `password`. ## `password` password to set. Sets the state of saving passwords for the mount operation. ## `save` a set of `PasswordSave` flags. Sets the mount operation's PIM to `pim`. Feature: `v2_58` ## `pim` an unsigned integer. Sets the user name within `self` to `username`. ## `username` input username. Emitted by the backend when e.g. a device becomes unavailable while a mount operation is in progress. Implementations of GMountOperation should handle this signal by dismissing open password dialogs. Emitted when a mount operation asks the user for a password. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a ``GtkMessageDialog``. ## `message` string containing a message to display to the user. ## `default_user` string containing the default user name. ## `default_domain` string containing the default domain. ## `flags` a set of `AskPasswordFlags`. Emitted when asking the user a question and gives a list of choices for the user to choose from. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a ``GtkMessageDialog``. ## `message` string containing a message to display to the user. ## `choices` an array of strings for each possible choice. Emitted when the user has replied to the mount operation. ## `result` a `MountOperationResult` indicating how the request was handled Emitted when one or more processes are blocking an operation e.g. unmounting/ejecting a `Mount` or stopping a `Drive`. Note that this signal may be emitted several times to update the list of blocking processes as processes close files. The application should only respond with `MountOperationExt::reply` to the latest signal (setting `MountOperation:choice` to the choice the user made). If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a ``GtkMessageDialog``. ## `message` string containing a message to display to the user. ## `processes` an array of `glib::Pid` for processes blocking the operation. ## `choices` an array of strings for each possible choice. Emitted when an unmount operation has been busy for more than some time (typically 1.5 seconds). When unmounting or ejecting a volume, the kernel might need to flush pending data in its buffers to the volume stable storage, and this operation can take a considerable amount of time. This signal may be emitted several times as long as the unmount operation is outstanding, and then one last time when the operation is completed, with `bytes_left` set to zero. Implementations of GMountOperation should handle this signal by showing an UI notification, and then dismiss it, or show another notification of completion, when `bytes_left` reaches zero. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a ``GtkMessageDialog``. ## `message` string containing a mesage to display to the user ## `time_left` the estimated time left before the operation completes, in microseconds, or -1 ## `bytes_left` the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed Whether to use an anonymous user when authenticating. Whether to use an anonymous user when authenticating. The index of the user's choice when a question is asked during the mount operation. See the `MountOperation::ask-question` signal. The index of the user's choice when a question is asked during the mount operation. See the `MountOperation::ask-question` signal. The domain to use for the mount operation. The domain to use for the mount operation. Whether the device to be unlocked is a TCRYPT hidden volume. See https://www.veracrypt.fr/en/Hidden`20Volume.html`. Feature: `v2_58` Whether the device to be unlocked is a TCRYPT hidden volume. See https://www.veracrypt.fr/en/Hidden`20Volume.html`. Feature: `v2_58` Whether the device to be unlocked is a TCRYPT system volume. In this context, a system volume is a volume with a bootloader and operating system installed. This is only supported for Windows operating systems. For further documentation, see https://www.veracrypt.fr/en/System`20Encryption.html`. Feature: `v2_58` Whether the device to be unlocked is a TCRYPT system volume. In this context, a system volume is a volume with a bootloader and operating system installed. This is only supported for Windows operating systems. For further documentation, see https://www.veracrypt.fr/en/System`20Encryption.html`. Feature: `v2_58` The password that is used for authentication when carrying out the mount operation. The password that is used for authentication when carrying out the mount operation. Determines if and how the password information should be saved. Determines if and how the password information should be saved. The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See https://www.veracrypt.fr/en/Personal`20Iterations`%20Multiplier`20`(PIM).html. Feature: `v2_58` The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See https://www.veracrypt.fr/en/Personal`20Iterations`%20Multiplier`20`(PIM).html. Feature: `v2_58` The user name that is used for authentication when carrying out the mount operation. The user name that is used for authentication when carrying out the mount operation. `MountOperationResult` is returned as a result when a request for information is send by the mounting operation. The request was fulfilled and the user specified data is now available The user requested the mount operation to be aborted The request was unhandled (i.e. not implemented) `NetworkAddress` provides an easy way to resolve a hostname and then attempt to connect to that host, handling the possibility of multiple IP addresses and multiple address families. See `SocketConnectable` for and example of using the connectable interface. # Implements [`NetworkAddressExt`](trait.NetworkAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `NetworkAddress` methods. # Implementors [`NetworkAddress`](struct.NetworkAddress.html) Creates a new `SocketConnectable` for connecting to the given `hostname` and `port`. Note that depending on the configuration of the machine, a `hostname` of `localhost` may refer to the IPv4 loopback address only, or to both IPv4 and IPv6; use `NetworkAddress::new_loopback` to create a `NetworkAddress` that is guaranteed to resolve to both addresses. ## `hostname` the hostname ## `port` the port # Returns the new `NetworkAddress` Creates a new `SocketConnectable` for connecting to the local host over a loopback connection to the given `port`. This is intended for use in connecting to local services which may be running on IPv4 or IPv6. The connectable will return IPv4 and IPv6 loopback addresses, regardless of how the host resolves `localhost`. By contrast, `NetworkAddress::new` will often only return an IPv4 address when resolving `localhost`, and an IPv6 address for `localhost6`. `NetworkAddressExt::get_hostname` will always return `localhost` for `GNetworkAddresses` created with this constructor. Feature: `v2_44` ## `port` the port # Returns the new `NetworkAddress` Creates a new `SocketConnectable` for connecting to the given `hostname` and `port`. May fail and return `None` in case parsing `host_and_port` fails. `host_and_port` may be in any of a number of recognised formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. If no port is specified in `host_and_port` then `default_port` will be used as the port number to connect to. In general, `host_and_port` is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and `default_port` is expected to be provided by the application. (The port component of `host_and_port` can also be specified as a service name rather than as a numeric port, but this functionality is deprecated, because it depends on the contents of /etc/services, which is generally quite sparse on platforms other than Linux.) ## `host_and_port` the hostname and optionally a port ## `default_port` the default port if not in `host_and_port` # Returns the new `NetworkAddress`, or `None` on error Creates a new `SocketConnectable` for connecting to the given `uri`. May fail and return `None` in case parsing `uri` fails. Using this rather than `NetworkAddress::new` or `NetworkAddress::parse` allows `SocketClient` to determine when to use application-specific proxy protocols. ## `uri` the hostname and optionally a port ## `default_port` The default port if none is found in the URI # Returns the new `NetworkAddress`, or `None` on error Gets `self`'s hostname. This might be either UTF-8 or ASCII-encoded, depending on what `self` was created with. # Returns `self`'s hostname Gets `self`'s port number # Returns `self`'s port (which may be 0) Gets `self`'s scheme # Returns `self`'s scheme (`None` if not built from URI) The host's network connectivity state, as reported by `NetworkMonitor`. The host is not configured with a route to the Internet; it may or may not be connected to a local network. The host is connected to a network, but does not appear to be able to reach the full Internet, perhaps due to upstream network problems. The host is behind a captive portal and cannot reach the full Internet. The host is connected to a network, and appears to be able to reach the full Internet. Feature: `v2_44` `NetworkMonitor` provides an easy-to-use cross-platform API for monitoring network connectivity. On Linux, the available implementations are based on the kernel's netlink interface and on NetworkManager. There is also an implementation for use inside Flatpak sandboxes. # Implements [`NetworkMonitorExt`](trait.NetworkMonitorExt.html) Trait containing all `NetworkMonitor` methods. # Implementors [`NetworkMonitor`](struct.NetworkMonitor.html) Gets the default `NetworkMonitor` for the system. # Returns a `NetworkMonitor` Attempts to determine whether or not the host pointed to by `connectable` can be reached, without actually trying to connect to it. This may return `true` even when `NetworkMonitor:network-available` is `false`, if, for example, `self` can determine that `connectable` refers to a host on a local network. If `self` believes that an attempt to connect to `connectable` will succeed, it will return `true`. Otherwise, it will return `false` and set `error` to an appropriate error (such as `IOErrorEnum::HostUnreachable`). Note that although this does not attempt to connect to `connectable`, it may still block for a brief period of time (eg, trying to do multicast DNS on the local network), so if you do not want to block, you should use `NetworkMonitor::can_reach_async`. ## `connectable` a `SocketConnectable` ## `cancellable` a `Cancellable`, or `None` # Returns `true` if `connectable` is reachable, `false` if not. Asynchronously attempts to determine whether or not the host pointed to by `connectable` can be reached, without actually trying to connect to it. For more details, see `NetworkMonitor::can_reach`. When the operation is finished, `callback` will be called. You can then call `NetworkMonitor::can_reach_finish` to get the result of the operation. ## `connectable` a `SocketConnectable` ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an async network connectivity test. See `NetworkMonitor::can_reach_async`. ## `result` a `AsyncResult` # Returns `true` if network is reachable, `false` if not. Gets a more detailed networking state than `NetworkMonitor::get_network_available`. If `NetworkMonitor:network-available` is `false`, then the connectivity state will be `NetworkConnectivity::Local`. If `NetworkMonitor:network-available` is `true`, then the connectivity state will be `NetworkConnectivity::Full` (if there is full Internet connectivity), `NetworkConnectivity::Limited` (if the host has a default route, but appears to be unable to actually reach the full Internet), or `NetworkConnectivity::Portal` (if the host is trapped behind a "captive portal" that requires some sort of login or acknowledgement before allowing full Internet access). Note that in the case of `NetworkConnectivity::Limited` and `NetworkConnectivity::Portal`, it is possible that some sites are reachable but others are not. In this case, applications can attempt to connect to remote servers, but should gracefully fall back to their "offline" behavior if the connection attempt fails. Feature: `v2_44` # Returns the network connectivity state Checks if the network is available. "Available" here means that the system has a default route available for at least one of IPv4 or IPv6. It does not necessarily imply that the public Internet is reachable. See `NetworkMonitor:network-available` for more details. # Returns whether the network is available Checks if the network is metered. See `NetworkMonitor:network-metered` for more details. Feature: `v2_46` # Returns whether the connection is metered Emitted when the network configuration changes. ## `network_available` the current value of `NetworkMonitor:network-available` More detailed information about the host's network connectivity. See `NetworkMonitor::get_connectivity` and `NetworkConnectivity` for more details. Feature: `v2_44` Whether the network is considered available. That is, whether the system has a default route for at least one of IPv4 or IPv6. Real-world networks are of course much more complicated than this; the machine may be connected to a wifi hotspot that requires payment before allowing traffic through, or may be connected to a functioning router that has lost its own upstream connectivity. Some hosts might only be accessible when a VPN is active. Other hosts might only be accessible when the VPN is not active. Thus, it is best to use `NetworkMonitor::can_reach` or `NetworkMonitor::can_reach_async` to test for reachability on a host-by-host basis. (On the other hand, when the property is `false`, the application can reasonably expect that no remote hosts at all are reachable, and should indicate this to the user in its UI.) See also `NetworkMonitor::network-changed`. Whether the network is considered metered. That is, whether the system has traffic flowing through the default connection that is subject to limitations set by service providers. For example, traffic might be billed by the amount of data transmitted, or there might be a quota on the amount of traffic per month. This is typical with tethered connections (3G and 4G) and in such situations, bandwidth intensive applications may wish to avoid network activity where possible if it will cost the user money or use up their limited quota. If more information is required about specific devices then the system network management API should be used instead (for example, NetworkManager or ConnMan). If this information is not available then no networks will be marked as metered. See also `NetworkMonitor:network-available`. Feature: `v2_46` Like `NetworkAddress` does with hostnames, `NetworkService` provides an easy way to resolve a SRV record, and then attempt to connect to one of the hosts that implements that service, handling service priority/weighting, multiple IP addresses, and multiple address families. See `SrvTarget` for more information about SRV records, and see `SocketConnectable` for and example of using the connectable interface. # Implements [`NetworkServiceExt`](trait.NetworkServiceExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `NetworkService` methods. # Implementors [`NetworkService`](struct.NetworkService.html) Creates a new `NetworkService` representing the given `service`, `protocol`, and `domain`. This will initially be unresolved; use the `SocketConnectable` interface to resolve it. ## `service` the service type to look up (eg, "ldap") ## `protocol` the networking protocol to use for `service` (eg, "tcp") ## `domain` the DNS domain to look up the service in # Returns a new `NetworkService` Gets the domain that `self` serves. This might be either UTF-8 or ASCII-encoded, depending on what `self` was created with. # Returns `self`'s domain name Gets `self`'s protocol name (eg, "tcp"). # Returns `self`'s protocol name Get's the URI scheme used to resolve proxies. By default, the service name is used as scheme. # Returns `self`'s scheme name Gets `self`'s service name (eg, "ldap"). # Returns `self`'s service name Set's the URI scheme used to resolve proxies. By default, the service name is used as scheme. ## `scheme` a URI scheme `Notification` is a mechanism for creating a notification to be shown to the user -- typically as a pop-up notification presented by the desktop environment shell. The key difference between `Notification` and other similar APIs is that, if supported by the desktop environment, notifications sent with `Notification` will persist after the application has exited, and even across system reboots. Since the user may click on a notification while the application is not running, applications using `Notification` should be able to be started as a D-Bus service, using `Application`. User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: "app." actions). It is not possible to route user interaction through the notification itself, because the object will not exist if the application is autostarted as a result of a notification being clicked. A notification can be sent with `ApplicationExt::send_notification`. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Notification` with `title` as its title. After populating `notification` with more details, it can be sent to the desktop shell with `ApplicationExt::send_notification`. Changing any properties after this call will not have any effect until resending `notification`. ## `title` the title of the notification # Returns a new `Notification` instance Adds a button to `self` that activates the action in `detailed_action` when clicked. That action must be an application-wide action (starting with "app."). If `detailed_action` contains a target, the action will be activated with that target as its parameter. See `Action::parse_detailed_name` for a description of the format for `detailed_action`. ## `label` label of the button ## `detailed_action` a detailed action name Adds a button to `self` that activates `action` when clicked. `action` must be an application-wide action (it must start with "app."). If `target_format` is given, it is used to collect remaining positional parameters into a `glib::Variant` instance, similar to `glib::Variant::new`. `action` will be activated with that `glib::Variant` as its parameter. ## `label` label of the button ## `action` an action name ## `target_format` a `glib::Variant` format string, or `None` Adds a button to `self` that activates `action` when clicked. `action` must be an application-wide action (it must start with "app."). If `target` is non-`None`, `action` will be activated with `target` as its parameter. ## `label` label of the button ## `action` an action name ## `target` a `glib::Variant` to use as `action`'s parameter, or `None` Sets the body of `self` to `body`. ## `body` the new body for `self`, or `None` Sets the default action of `self` to `detailed_action`. This action is activated when the notification is clicked on. The action in `detailed_action` must be an application-wide action (it must start with "app."). If `detailed_action` contains a target, the given action will be activated with that target as its parameter. See `Action::parse_detailed_name` for a description of the format for `detailed_action`. When no default action is set, the application that the notification was sent on is activated. ## `detailed_action` a detailed action name Sets the default action of `self` to `action`. This action is activated when the notification is clicked on. It must be an application-wide action (it must start with "app."). If `target_format` is given, it is used to collect remaining positional parameters into a `glib::Variant` instance, similar to `glib::Variant::new`. `action` will be activated with that `glib::Variant` as its parameter. When no default action is set, the application that the notification was sent on is activated. ## `action` an action name ## `target_format` a `glib::Variant` format string, or `None` Sets the default action of `self` to `action`. This action is activated when the notification is clicked on. It must be an application-wide action (start with "app."). If `target` is non-`None`, `action` will be activated with `target` as its parameter. When no default action is set, the application that the notification was sent on is activated. ## `action` an action name ## `target` a `glib::Variant` to use as `action`'s parameter, or `None` Sets the icon of `self` to `icon`. ## `icon` the icon to be shown in `self`, as a `Icon` Sets the priority of `self` to `priority`. See `NotificationPriority` for possible values. ## `priority` a `NotificationPriority` Sets the title of `self` to `title`. ## `title` the new title for `self` Priority levels for `GNotifications`. the default priority, to be used for the majority of notifications (for example email messages, software updates, completed download/sync operations) for notifications that do not require immediate attention - typically used for contextual background information, such as contact birthdays or local weather for events that require more attention, usually because responses are time-sensitive (for example chat and SMS messages or alarms) for urgent notifications, or notifications that require a response in a short space of time (for example phone calls or emergency warnings) `OutputStream` has functions to write to a stream (`OutputStreamExt::write`), to close a stream (`OutputStreamExt::close`) and to flush pending writes (`OutputStreamExt::flush`). To copy the content of an input stream to an output stream without manually handling the reads and writes, use `OutputStreamExt::splice`. See the documentation for `IOStream` for details of thread safety of streaming APIs. All of these functions have async variants too. # Implements [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `OutputStream` methods. # Implementors [`FileOutputStream`](struct.FileOutputStream.html), [`FilterOutputStream`](struct.FilterOutputStream.html), [`MemoryOutputStream`](struct.MemoryOutputStream.html), [`OutputStream`](struct.OutputStream.html), [`PollableOutputStream`](struct.PollableOutputStream.html), [`UnixOutputStream`](struct.UnixOutputStream.html) Clears the pending flag on `self`. Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return `IOErrorEnum::Closed`. Closing a stream multiple times will not return an error. Closing a stream will automatically flush any outstanding buffers in the stream. Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details. On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return `IOErrorEnum::Closed` for all operations. Still, it is important to check and report the error to the user, otherwise there might be a loss of data as all data might not be written. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. Cancelling a close will still leave the stream closed, but there some streams can use a faster close that doesn't block to e.g. check errors. On cancellation (as with any error) there is no guarantee that all written data will reach the target. ## `cancellable` optional cancellable object # Returns `true` on success, `false` on failure Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished `callback` will be called. You can then call `OutputStreamExt::close_finish` to get the result of the operation. For behaviour details see `OutputStreamExt::close`. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. ## `io_priority` the io priority of the request. ## `cancellable` optional cancellable object ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Closes an output stream. ## `result` a `AsyncResult`. # Returns `true` if stream was successfully closed, `false` otherwise. Forces a write of all user-space buffered data for the given `self`. Will block during the operation. Closing the stream will implicitly cause a flush. This function is optional for inherited classes. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional cancellable object # Returns `true` on success, `false` on error Forces an asynchronous write of all user-space buffered data for the given `self`. For behaviour details see `OutputStreamExt::flush`. When the operation is finished `callback` will be called. You can then call `OutputStreamExt::flush_finish` to get the result of the operation. ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes flushing an output stream. ## `result` a GAsyncResult. # Returns `true` if flush operation succeeded, `false` otherwise. Checks if an output stream has pending actions. # Returns `true` if `self` has pending actions. Checks if an output stream has already been closed. # Returns `true` if `self` is closed. `false` otherwise. Checks if an output stream is being closed. This can be used inside e.g. a flush implementation to see if the flush (or other i/o operation) is called from within the closing operation. # Returns `true` if `self` is being closed. `false` otherwise. This is a utility function around `OutputStream::write_all`. It uses `g_strdup_vprintf` to turn `format` and @... into a string that is then written to `self`. See the documentation of `OutputStream::write_all` about the behavior of the actual write operation. Note that partial writes cannot be properly checked with this function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own `printf`-like wrapper around `OutputStreamExt::write` or `OutputStream::write_all`. ## `bytes_written` location to store the number of bytes that was written to the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `error` location to store the error occurring, or `None` to ignore ## `format` the format string. See the `printf` documentation # Returns `true` on success, `false` if there was an error Sets `self` to have actions pending. If the pending flag is already set or `self` is closed, it will return `false` and set `error`. # Returns `true` if pending was previously unset and is now set. Splices an input stream into an output stream. ## `source` a `InputStream`. ## `flags` a set of `OutputStreamSpliceFlags`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `gssize` containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than `G_MAXSSIZE`, then that will be returned, and there is no way to determine the actual number of bytes spliced. Splices a stream asynchronously. When the operation is finished `callback` will be called. You can then call `OutputStreamExt::splice_finish` to get the result of the operation. For the synchronous, blocking version of this function, see `OutputStreamExt::splice`. ## `source` a `InputStream`. ## `flags` a set of `OutputStreamSpliceFlags`. ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`. ## `user_data` user data passed to `callback`. Finishes an asynchronous stream splice operation. ## `result` a `AsyncResult`. # Returns a `gssize` of the number of bytes spliced. Note that if the number of bytes spliced is greater than `G_MAXSSIZE`, then that will be returned, and there is no way to determine the actual number of bytes spliced. This is a utility function around `OutputStream::write_all`. It uses `g_strdup_vprintf` to turn `format` and `args` into a string that is then written to `self`. See the documentation of `OutputStream::write_all` about the behavior of the actual write operation. Note that partial writes cannot be properly checked with this function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own `printf`-like wrapper around `OutputStreamExt::write` or `OutputStream::write_all`. ## `bytes_written` location to store the number of bytes that was written to the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `error` location to store the error occurring, or `None` to ignore ## `format` the format string. See the `printf` documentation ## `args` the parameters to insert into the format string # Returns `true` on success, `false` if there was an error Tries to write `count` bytes from `buffer` into the stream. Will block during the operation. If count is 0, returns 0 and does nothing. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, the number of bytes written to the stream is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, or if there is not enough storage in the stream. All writes block until at least one byte is written or an error occurs; 0 is never returned (unless `count` is 0). If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error -1 is returned and `error` is set accordingly. ## `buffer` the buffer containing the data to write. ## `count` the number of bytes to write ## `cancellable` optional cancellable object # Returns Number of bytes written, or -1 on error Tries to write `count` bytes from `buffer` into the stream. Will block during the operation. This function is similar to `OutputStreamExt::write`, except it tries to write as many bytes as requested, only stopping on an error. On a successful write of `count` bytes, `true` is returned, and `bytes_written` is set to `count`. If there is an error during the operation `false` is returned and `error` is set to indicate the error status. As a special exception to the normal conventions for functions that use `glib::Error`, if this function returns `false` (and sets `error`) then `bytes_written` will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around `OutputStreamExt::write`. ## `buffer` the buffer containing the data to write. ## `count` the number of bytes to write ## `bytes_written` location to store the number of bytes that was written to the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` on success, `false` if there was an error Request an asynchronous write of `count` bytes from `buffer` into the stream. When the operation is finished `callback` will be called. You can then call `OutputStreamExt::write_all_finish` to get the result of the operation. This is the asynchronous version of `OutputStream::write_all`. Call `OutputStreamExt::write_all_finish` to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`. Note that no copy of `buffer` will be made, so it must stay valid until `callback` is called. Feature: `v2_44` ## `buffer` the buffer containing the data to write ## `count` the number of bytes to write ## `io_priority` the io priority of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous stream write operation started with `OutputStream::write_all_async`. As a special exception to the normal conventions for functions that use `glib::Error`, if this function returns `false` (and sets `error`) then `bytes_written` will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around `OutputStream::write_async`. Feature: `v2_44` ## `result` a `AsyncResult` ## `bytes_written` location to store the number of bytes that was written to the stream # Returns `true` on success, `false` if there was an error Request an asynchronous write of `count` bytes from `buffer` into the stream. When the operation is finished `callback` will be called. You can then call `OutputStreamExt::write_finish` to get the result of the operation. During an async request no other sync and async calls are allowed, and will result in `IOErrorEnum::Pending` errors. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, the number of bytes written will be passed to the `callback`. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, but generally we try to write as many bytes as requested. You are guaranteed that this method will never fail with `IOErrorEnum::WouldBlock` - if `self` can't accept more data, the method will just wait until this changes. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`. The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all. For the synchronous, blocking version of this function, see `OutputStreamExt::write`. Note that no copy of `buffer` will be made, so it must stay valid until `callback` is called. See `OutputStreamExt::write_bytes_async` for a `glib::Bytes` version that will automatically hold a reference to the contents (without copying) for the duration of the call. ## `buffer` the buffer containing the data to write. ## `count` the number of bytes to write ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function A wrapper function for `OutputStreamExt::write` which takes a `glib::Bytes` as input. This can be more convenient for use by language bindings or in other cases where the refcounted nature of `glib::Bytes` is helpful over a bare pointer interface. However, note that this function may still perform partial writes, just like `OutputStreamExt::write`. If that occurs, to continue writing, you will need to create a new `glib::Bytes` containing just the remaining bytes, using `glib::Bytes::new_from_bytes`. Passing the same `glib::Bytes` instance multiple times potentially can result in duplicated data in the output stream. ## `bytes` the `glib::Bytes` to write ## `cancellable` optional cancellable object # Returns Number of bytes written, or -1 on error This function is similar to `OutputStream::write_async`, but takes a `glib::Bytes` as input. Due to the refcounted nature of `glib::Bytes`, this allows the stream to avoid taking a copy of the data. However, note that this function may still perform partial writes, just like `OutputStream::write_async`. If that occurs, to continue writing, you will need to create a new `glib::Bytes` containing just the remaining bytes, using `glib::Bytes::new_from_bytes`. Passing the same `glib::Bytes` instance multiple times potentially can result in duplicated data in the output stream. For the synchronous, blocking version of this function, see `OutputStreamExt::write_bytes`. ## `bytes` The bytes to write ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes a stream write-from-`glib::Bytes` operation. ## `result` a `AsyncResult`. # Returns a `gssize` containing the number of bytes written to the stream. Finishes a stream write operation. ## `result` a `AsyncResult`. # Returns a `gssize` containing the number of bytes written to the stream. `PasswordSave` is used to indicate the lifespan of a saved password. `Gvfs` stores passwords in the Gnome keyring when this flag allows it to, and later retrieves it again from there. never save a password. save a password for the session. save a password permanently. A `Permission` represents the status of the caller's permission to perform a certain action. You can query if the action is currently allowed and if it is possible to acquire the permission so that the action will be allowed in the future. There is also an API to actually acquire the permission and one to release it. As an example, a `Permission` might represent the ability for the user to write to a `Settings` object. This `Permission` object could then be used to decide if it is appropriate to show a "Click here to unlock" button in a dialog and to provide the mechanism to invoke when that button is clicked. # Implements [`PermissionExt`](trait.PermissionExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Permission` methods. # Implementors [`Permission`](struct.Permission.html), [`SimplePermission`](struct.SimplePermission.html) Attempts to acquire the permission represented by `self`. The precise method by which this happens depends on the permission and the underlying authentication mechanism. A simple example is that a dialog may appear asking the user to enter their password. You should check with `PermissionExt::get_can_acquire` before calling this function. If the permission is acquired then `true` is returned. Otherwise, `false` is returned and `error` is set appropriately. This call is blocking, likely for a very long time (in the case that user interaction is required). See `PermissionExt::acquire_async` for the non-blocking version. ## `cancellable` a `Cancellable`, or `None` # Returns `true` if the permission was successfully acquired Attempts to acquire the permission represented by `self`. This is the first half of the asynchronous version of `PermissionExt::acquire`. ## `cancellable` a `Cancellable`, or `None` ## `callback` the `GAsyncReadyCallback` to call when done ## `user_data` the user data to pass to `callback` Collects the result of attempting to acquire the permission represented by `self`. This is the second half of the asynchronous version of `PermissionExt::acquire`. ## `result` the `AsyncResult` given to the `GAsyncReadyCallback` # Returns `true` if the permission was successfully acquired Gets the value of the 'allowed' property. This property is `true` if the caller currently has permission to perform the action that `self` represents the permission to perform. # Returns the value of the 'allowed' property Gets the value of the 'can-acquire' property. This property is `true` if it is generally possible to acquire the permission by calling `PermissionExt::acquire`. # Returns the value of the 'can-acquire' property Gets the value of the 'can-release' property. This property is `true` if it is generally possible to release the permission by calling `PermissionExt::release`. # Returns the value of the 'can-release' property This function is called by the `Permission` implementation to update the properties of the permission. You should never call this function except from a `Permission` implementation. GObject notify signals are generated, as appropriate. ## `allowed` the new value for the 'allowed' property ## `can_acquire` the new value for the 'can-acquire' property ## `can_release` the new value for the 'can-release' property Attempts to release the permission represented by `self`. The precise method by which this happens depends on the permission and the underlying authentication mechanism. In most cases the permission will be dropped immediately without further action. You should check with `PermissionExt::get_can_release` before calling this function. If the permission is released then `true` is returned. Otherwise, `false` is returned and `error` is set appropriately. This call is blocking, likely for a very long time (in the case that user interaction is required). See `PermissionExt::release_async` for the non-blocking version. ## `cancellable` a `Cancellable`, or `None` # Returns `true` if the permission was successfully released Attempts to release the permission represented by `self`. This is the first half of the asynchronous version of `PermissionExt::release`. ## `cancellable` a `Cancellable`, or `None` ## `callback` the `GAsyncReadyCallback` to call when done ## `user_data` the user data to pass to `callback` Collects the result of attempting to release the permission represented by `self`. This is the second half of the asynchronous version of `PermissionExt::release`. ## `result` the `AsyncResult` given to the `GAsyncReadyCallback` # Returns `true` if the permission was successfully released `true` if the caller currently has permission to perform the action that `permission` represents the permission to perform. `true` if it is generally possible to acquire the permission by calling `PermissionExt::acquire`. `true` if it is generally possible to release the permission by calling `PermissionExt::release`. `PollableInputStream` is implemented by `GInputStreams` that can be polled for readiness to read. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. # Implements [`PollableInputStreamExt`](trait.PollableInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableInputStreamExtManual`](prelude/trait.PollableInputStreamExtManual.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `PollableInputStream` methods. # Implementors [`ConverterInputStream`](struct.ConverterInputStream.html), [`MemoryInputStream`](struct.MemoryInputStream.html), [`PollableInputStream`](struct.PollableInputStream.html), [`UnixInputStream`](struct.UnixInputStream.html) Checks if `self` is actually pollable. Some classes may implement `PollableInputStream` but have only certain instances of that class be pollable. If this method returns `false`, then the behavior of other `PollableInputStream` methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. # Returns `true` if `self` is pollable, `false` if not. Creates a `glib::Source` that triggers when `self` can be read, or `cancellable` is triggered or an error occurs. The callback on the source is of the `GPollableSourceFunc` type. As with `PollableInputStream::is_readable`, it is possible that the stream may not actually be readable even after the source triggers, so you should use `PollableInputStream::read_nonblocking` rather than `InputStream::read` from the callback. ## `cancellable` a `Cancellable`, or `None` # Returns a new `glib::Source` Checks if `self` can be read. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to `InputStream::read` after this returns `true` would still block. To guarantee non-blocking behavior, you should always use `PollableInputStream::read_nonblocking`, which will return a `IOErrorEnum::WouldBlock` error rather than blocking. # Returns `true` if `self` is readable, `false` if not. If an error has occurred on `self`, this will result in `PollableInputStream::is_readable` returning `true`, and the next attempt to read will return the error. Attempts to read up to `count` bytes from `self` into `buffer`, as with `InputStream::read`. If `self` is not currently readable, this will immediately return `IOErrorEnum::WouldBlock`, and you can use `PollableInputStream::create_source` to create a `glib::Source` that will be triggered when `self` is readable. Note that since this method never blocks, you cannot actually use `cancellable` to cancel it. However, it will return an error if `cancellable` has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. ## `buffer` a buffer to read data into (which should be at least `count` bytes long). ## `count` the number of bytes you want to read ## `cancellable` a `Cancellable`, or `None` # Returns the number of bytes read, or -1 on error (including `IOErrorEnum::WouldBlock`). `PollableOutputStream` is implemented by `GOutputStreams` that can be polled for readiness to write. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. # Implements [`PollableOutputStreamExt`](trait.PollableOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableOutputStreamExtManual`](prelude/trait.PollableOutputStreamExtManual.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `PollableOutputStream` methods. # Implementors [`ConverterOutputStream`](struct.ConverterOutputStream.html), [`MemoryOutputStream`](struct.MemoryOutputStream.html), [`PollableOutputStream`](struct.PollableOutputStream.html), [`UnixOutputStream`](struct.UnixOutputStream.html) Checks if `self` is actually pollable. Some classes may implement `PollableOutputStream` but have only certain instances of that class be pollable. If this method returns `false`, then the behavior of other `PollableOutputStream` methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. # Returns `true` if `self` is pollable, `false` if not. Creates a `glib::Source` that triggers when `self` can be written, or `cancellable` is triggered or an error occurs. The callback on the source is of the `GPollableSourceFunc` type. As with `PollableOutputStream::is_writable`, it is possible that the stream may not actually be writable even after the source triggers, so you should use `PollableOutputStream::write_nonblocking` rather than `OutputStreamExt::write` from the callback. ## `cancellable` a `Cancellable`, or `None` # Returns a new `glib::Source` Checks if `self` can be written. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to `OutputStreamExt::write` after this returns `true` would still block. To guarantee non-blocking behavior, you should always use `PollableOutputStream::write_nonblocking`, which will return a `IOErrorEnum::WouldBlock` error rather than blocking. # Returns `true` if `self` is writable, `false` if not. If an error has occurred on `self`, this will result in `PollableOutputStream::is_writable` returning `true`, and the next attempt to write will return the error. Attempts to write up to `count` bytes from `buffer` to `self`, as with `OutputStreamExt::write`. If `self` is not currently writable, this will immediately return `IOErrorEnum::WouldBlock`, and you can use `PollableOutputStream::create_source` to create a `glib::Source` that will be triggered when `self` is writable. Note that since this method never blocks, you cannot actually use `cancellable` to cancel it. However, it will return an error if `cancellable` has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. Also note that if `IOErrorEnum::WouldBlock` is returned some underlying transports like D/TLS require that you send the same `buffer` and `count`. ## `buffer` a buffer to write data from ## `count` the number of bytes you want to write ## `cancellable` a `Cancellable`, or `None` # Returns the number of bytes written, or -1 on error (including `IOErrorEnum::WouldBlock`). A `PropertyAction` is a way to get a `Action` with a state value reflecting and controlling the value of a `gobject::Object` property. The state of the action will correspond to the value of the property. Changing it will change the property (assuming the requested value matches the requirements as specified in the `gobject::ParamSpec`). Only the most common types are presently supported. Booleans are mapped to booleans, strings to strings, signed/unsigned integers to int32/uint32 and floats and doubles to doubles. If the property is an enum then the state will be string-typed and conversion will automatically be performed between the enum value and "nick" string as per the `gobject::EnumValue` table. Flags types are not currently supported. Properties of object types, boxed types and pointer types are not supported and probably never will be. Properties of `glib::Variant` types are not currently supported. If the property is boolean-valued then the action will have a NULL parameter type, and activating the action (with no parameter) will toggle the value of the property. In all other cases, the parameter type will correspond to the type of the property. The general idea here is to reduce the number of locations where a particular piece of state is kept (and therefore has to be synchronised between). `PropertyAction` does not have a separate state that is kept in sync with the property value -- its state is the property value. For example, it might be useful to create a `Action` corresponding to the "visible-child-name" property of a ``GtkStack`` so that the current page can be switched from a menu. The active radio indication in the menu is then directly determined from the active page of the ``GtkStack``. An anti-example would be binding the "active-id" property on a ``GtkComboBox``. This is because the state of the combobox itself is probably uninteresting and is actually being used to control something else. Another anti-example would be to bind to the "visible-child-name" property of a ``GtkStack`` if this value is actually stored in `Settings`. In that case, the real source of the value is `Settings`. If you want a `Action` to control a setting stored in `Settings`, see `SettingsExt::create_action` instead, and possibly combine its use with `SettingsExt::bind`. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ActionExt`](trait.ActionExt.html) Creates a `Action` corresponding to the value of property `property_name` on `object`. The property must be existent and readable and writable (and not construct-only). This function takes a reference on `object` and doesn't release it until the action is destroyed. ## `name` the name of the action to create ## `object` the object that has the property to wrap ## `property_name` the name of the property # Returns a new `PropertyAction` If `action` is currently enabled. If the action is disabled then calls to `Action::activate` and `Action::change_state` have no effect. If `true`, the state of the action will be the negation of the property value, provided the property is boolean. Feature: `v2_46` If `true`, the state of the action will be the negation of the property value, provided the property is boolean. Feature: `v2_46` The name of the action. This is mostly meaningful for identifying the action once it has been added to a `ActionMap`. The name of the action. This is mostly meaningful for identifying the action once it has been added to a `ActionMap`. The object to wrap a property on. The object must be a non-`None` `gobject::Object` with properties. The type of the parameter that must be given when activating the action. The name of the property to wrap on the object. The property must exist on the passed-in object and it must be readable and writable (and not construct-only). The state of the action, or `None` if the action is stateless. The `glib::VariantType` of the state that the action has, or `None` if the action is stateless. A `Proxy` handles connecting to a remote host via a given type of proxy server. It is implemented by the 'gio-proxy' extension point. The extensions are named after their proxy protocol name. As an example, a SOCKS5 proxy implementation can be retrieved with the name 'socks5' using the function `IOExtensionPoint::get_extension_by_name`. # Implements [`ProxyExt`](trait.ProxyExt.html) Trait containing all `Proxy` methods. # Implementors [`Proxy`](struct.Proxy.html) Lookup "gio-proxy" extension point for a proxy implementation that supports specified protocol. ## `protocol` the proxy protocol name (e.g. http, socks, etc) # Returns return a `Proxy` or NULL if protocol is not supported. Given `connection` to communicate with a proxy (eg, a `SocketConnection` that is connected to the proxy server), this does the necessary handshake to connect to `proxy_address`, and if required, wraps the `IOStream` to handle proxy payload. ## `connection` a `IOStream` ## `proxy_address` a `ProxyAddress` ## `cancellable` a `Cancellable` # Returns a `IOStream` that will replace `connection`. This might be the same as `connection`, in which case a reference will be added. Asynchronous version of `Proxy::connect`. ## `connection` a `IOStream` ## `proxy_address` a `ProxyAddress` ## `cancellable` a `Cancellable` ## `callback` a `GAsyncReadyCallback` ## `user_data` callback data See `Proxy::connect`. ## `result` a `AsyncResult` # Returns a `IOStream`. Some proxy protocols expect to be passed a hostname, which they will resolve to an IP address themselves. Others, like SOCKS4, do not allow this. This function will return `false` if `self` is implementing such a protocol. When `false` is returned, the caller should resolve the destination hostname first, and then pass a `ProxyAddress` containing the stringified IP address to `Proxy::connect` or `Proxy::connect_async`. # Returns `true` if hostname resolution is supported. Support for proxied `InetSocketAddress`. # Implements [`ProxyAddressExt`](trait.ProxyAddressExt.html), [`InetSocketAddressExt`](trait.InetSocketAddressExt.html), [`SocketAddressExt`](trait.SocketAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `ProxyAddress` methods. # Implementors [`ProxyAddress`](struct.ProxyAddress.html) Creates a new `ProxyAddress` for `inetaddr` with `protocol` that should tunnel through `dest_hostname` and `dest_port`. (Note that this method doesn't set the `ProxyAddress:uri` or `ProxyAddress:destination-protocol` fields; use `gobject::Object::new` directly if you want to set those.) ## `inetaddr` The proxy server `InetAddress`. ## `port` The proxy server port. ## `protocol` The proxy protocol to support, in lower case (e.g. socks, http). ## `dest_hostname` The destination hostname the proxy should tunnel to. ## `dest_port` The destination port to tunnel to. ## `username` The username to authenticate to the proxy server (or `None`). ## `password` The password to authenticate to the proxy server (or `None`). # Returns a new `ProxyAddress` Gets `self`'s destination hostname; that is, the name of the host that will be connected to via the proxy, not the name of the proxy itself. # Returns the `self`'s destination hostname Gets `self`'s destination port; that is, the port on the destination host that will be connected to via the proxy, not the port number of the proxy itself. # Returns the `self`'s destination port Gets the protocol that is being spoken to the destination server; eg, "http" or "ftp". # Returns the `self`'s destination protocol Gets `self`'s password. # Returns the `self`'s password Gets `self`'s protocol. eg, "socks" or "http" # Returns the `self`'s protocol Gets the proxy URI that `self` was constructed from. # Returns the `self`'s URI, or `None` if unknown Gets `self`'s username. # Returns the `self`'s username The protocol being spoke to the destination host, or `None` if the `ProxyAddress` doesn't know. The protocol being spoke to the destination host, or `None` if the `ProxyAddress` doesn't know. The URI string that the proxy was constructed from (or `None` if the creator didn't specify this). The URI string that the proxy was constructed from (or `None` if the creator didn't specify this). `ProxyResolver` provides synchronous and asynchronous network proxy resolution. `ProxyResolver` is used within `SocketClient` through the method `SocketConnectable::proxy_enumerate`. Implementations of `ProxyResolver` based on libproxy and GNOME settings can be found in glib-networking. GIO comes with an implementation for use inside Flatpak portals. # Implements [`ProxyResolverExt`](trait.ProxyResolverExt.html) Trait containing all `ProxyResolver` methods. # Implementors [`ProxyResolver`](struct.ProxyResolver.html) Gets the default `ProxyResolver` for the system. # Returns the default `ProxyResolver`. Checks if `self` can be used on this system. (This is used internally; `ProxyResolver::get_default` will only return a proxy resolver that returns `true` for this method.) # Returns `true` if `self` is supported. Looks into the system proxy configuration to determine what proxy, if any, to use to connect to `uri`. The returned proxy URIs are of the form `://[user[:password]@]host:port` or `direct://`, where `` could be http, rtsp, socks or other proxying protocol. If you don't know what network protocol is being used on the socket, you should use `none` as the URI protocol. In this case, the resolver might still return a generic proxy type (such as SOCKS), but would not return protocol-specific proxy types (such as http). `direct://` is used when no proxy is needed. Direct connection should not be attempted unless it is part of the returned array of proxies. ## `uri` a URI representing the destination to connect to ## `cancellable` a `Cancellable`, or `None` # Returns A NULL-terminated array of proxy URIs. Must be freed with `g_strfreev`. Asynchronous lookup of proxy. See `ProxyResolver::lookup` for more details. ## `uri` a URI representing the destination to connect to ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call after resolution completes ## `user_data` data for `callback` Call this function to obtain the array of proxy URIs when `ProxyResolver::lookup_async` is complete. See `ProxyResolver::lookup` for more details. ## `result` the result passed to your `GAsyncReadyCallback` # Returns A NULL-terminated array of proxy URIs. Must be freed with `g_strfreev`. The GRemoteActionGroup interface is implemented by `ActionGroup` instances that either transmit action invocations to other processes or receive action invocations in the local process from other processes. The interface has `_full` variants of the two methods on `ActionGroup` used to activate actions: `ActionGroup::activate_action` and `ActionGroup::change_action_state`. These variants allow a "platform data" `glib::Variant` to be specified: a dictionary providing context for the action invocation (for example: timestamps, startup notification IDs, etc). `DBusActionGroup` implements `RemoteActionGroup`. This provides a mechanism to send platform data for action invocations over D-Bus. Additionally, `DBusConnection::export_action_group` will check if the exported `ActionGroup` implements `RemoteActionGroup` and use the `_full` variants of the calls if available. This provides a mechanism by which to receive platform data for action invocations that arrive by way of D-Bus. # Implements [`RemoteActionGroupExt`](trait.RemoteActionGroupExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html) Trait containing all `RemoteActionGroup` methods. # Implementors [`RemoteActionGroup`](struct.RemoteActionGroup.html) Activates the remote action. This is the same as `ActionGroup::activate_action` except that it allows for provision of "platform data" to be sent along with the activation request. This typically contains details such as the user interaction timestamp or startup notification information. `platform_data` must be non-`None` and must have the type `G_VARIANT_TYPE_VARDICT`. If it is floating, it will be consumed. ## `action_name` the name of the action to activate ## `parameter` the optional parameter to the activation ## `platform_data` the platform data to send Changes the state of a remote action. This is the same as `ActionGroup::change_action_state` except that it allows for provision of "platform data" to be sent along with the state change request. This typically contains details such as the user interaction timestamp or startup notification information. `platform_data` must be non-`None` and must have the type `G_VARIANT_TYPE_VARDICT`. If it is floating, it will be consumed. ## `action_name` the name of the action to change the state of ## `value` the new requested value for the state ## `platform_data` the platform data to send `Resolver` provides cancellable synchronous and asynchronous DNS resolution, for hostnames (`ResolverExt::lookup_by_address`, `ResolverExt::lookup_by_name` and their async variants) and SRV (service) records (`ResolverExt::lookup_service`). `NetworkAddress` and `NetworkService` provide wrappers around `Resolver` functionality that also implement `SocketConnectable`, making it easy to connect to a remote host/service. # Implements [`ResolverExt`](trait.ResolverExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Resolver` methods. # Implementors [`Resolver`](struct.Resolver.html) Frees `addresses` (which should be the return value from `ResolverExt::lookup_by_name` or `ResolverExt::lookup_by_name_finish`). (This is a convenience method; you can also simply free the results by hand.) ## `addresses` a `glib::List` of `InetAddress` Frees `targets` (which should be the return value from `ResolverExt::lookup_service` or `ResolverExt::lookup_service_finish`). (This is a convenience method; you can also simply free the results by hand.) ## `targets` a `glib::List` of `SrvTarget` Gets the default `Resolver`. You should unref it when you are done with it. `Resolver` may use its reference count as a hint about how many threads it should allocate for concurrent DNS resolutions. # Returns the default `Resolver`. Synchronously reverse-resolves `address` to determine its associated hostname. If the DNS resolution fails, `error` (if non-`None`) will be set to a value from `ResolverError`. If `cancellable` is non-`None`, it can be used to cancel the operation, in which case `error` (if non-`None`) will be set to `IOErrorEnum::Cancelled`. ## `address` the address to reverse-resolve ## `cancellable` a `Cancellable`, or `None` # Returns a hostname (either ASCII-only, or in ASCII-encoded form), or `None` on error. Begins asynchronously reverse-resolving `address` to determine its associated hostname, and eventually calls `callback`, which must call `ResolverExt::lookup_by_address_finish` to get the final result. ## `address` the address to reverse-resolve ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call after resolution completes ## `user_data` data for `callback` Retrieves the result of a previous call to `ResolverExt::lookup_by_address_async`. If the DNS resolution failed, `error` (if non-`None`) will be set to a value from `ResolverError`. If the operation was cancelled, `error` will be set to `IOErrorEnum::Cancelled`. ## `result` the result passed to your `GAsyncReadyCallback` # Returns a hostname (either ASCII-only, or in ASCII-encoded form), or `None` on error. Synchronously resolves `hostname` to determine its associated IP address(es). `hostname` may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around `InetAddress::new_from_string`). On success, `ResolverExt::lookup_by_name` will return a non-empty `glib::List` of `InetAddress`, sorted in order of preference and guaranteed to not contain duplicates. That is, if using the result to connect to `hostname`, you should attempt to connect to the first address first, then the second if the first fails, etc. If you are using the result to listen on a socket, it is appropriate to add each result using e.g. `SocketListenerExt::add_address`. If the DNS resolution fails, `error` (if non-`None`) will be set to a value from `ResolverError` and `None` will be returned. If `cancellable` is non-`None`, it can be used to cancel the operation, in which case `error` (if non-`None`) will be set to `IOErrorEnum::Cancelled`. If you are planning to connect to a socket on the resolved IP address, it may be easier to create a `NetworkAddress` and use its `SocketConnectable` interface. ## `hostname` the hostname to look up ## `cancellable` a `Cancellable`, or `None` # Returns a non-empty `glib::List` of `InetAddress`, or `None` on error. You must unref each of the addresses and free the list when you are done with it. (You can use `Resolver::free_addresses` to do this.) Begins asynchronously resolving `hostname` to determine its associated IP address(es), and eventually calls `callback`, which must call `ResolverExt::lookup_by_name_finish` to get the result. See `ResolverExt::lookup_by_name` for more details. ## `hostname` the hostname to look up the address of ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call after resolution completes ## `user_data` data for `callback` Retrieves the result of a call to `ResolverExt::lookup_by_name_async`. If the DNS resolution failed, `error` (if non-`None`) will be set to a value from `ResolverError`. If the operation was cancelled, `error` will be set to `IOErrorEnum::Cancelled`. ## `result` the result passed to your `GAsyncReadyCallback` # Returns a `glib::List` of `InetAddress`, or `None` on error. See `ResolverExt::lookup_by_name` for more details. Synchronously performs a DNS record lookup for the given `rrname` and returns a list of records as `glib::Variant` tuples. See `ResolverRecordType` for information on what the records contain for each `record_type`. If the DNS resolution fails, `error` (if non-`None`) will be set to a value from `ResolverError` and `None` will be returned. If `cancellable` is non-`None`, it can be used to cancel the operation, in which case `error` (if non-`None`) will be set to `IOErrorEnum::Cancelled`. ## `rrname` the DNS name to lookup the record for ## `record_type` the type of DNS record to lookup ## `cancellable` a `Cancellable`, or `None` # Returns a non-empty `glib::List` of `glib::Variant`, or `None` on error. You must free each of the records and the list when you are done with it. (You can use `glib::List::free_full` with `glib::Variant::unref` to do this.) Begins asynchronously performing a DNS lookup for the given `rrname`, and eventually calls `callback`, which must call `ResolverExt::lookup_records_finish` to get the final result. See `ResolverExt::lookup_records` for more details. ## `rrname` the DNS name to lookup the record for ## `record_type` the type of DNS record to lookup ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call after resolution completes ## `user_data` data for `callback` Retrieves the result of a previous call to `ResolverExt::lookup_records_async`. Returns a non-empty list of records as `glib::Variant` tuples. See `ResolverRecordType` for information on what the records contain. If the DNS resolution failed, `error` (if non-`None`) will be set to a value from `ResolverError`. If the operation was cancelled, `error` will be set to `IOErrorEnum::Cancelled`. ## `result` the result passed to your `GAsyncReadyCallback` # Returns a non-empty `glib::List` of `glib::Variant`, or `None` on error. You must free each of the records and the list when you are done with it. (You can use `glib::List::free_full` with `glib::Variant::unref` to do this.) Synchronously performs a DNS SRV lookup for the given `service` and `protocol` in the given `domain` and returns an array of `SrvTarget`. `domain` may be an ASCII-only or UTF-8 hostname. Note also that the `service` and `protocol` arguments do not include the leading underscore that appears in the actual DNS entry. On success, `ResolverExt::lookup_service` will return a non-empty `glib::List` of `SrvTarget`, sorted in order of preference. (That is, you should attempt to connect to the first target first, then the second if the first fails, etc.) If the DNS resolution fails, `error` (if non-`None`) will be set to a value from `ResolverError` and `None` will be returned. If `cancellable` is non-`None`, it can be used to cancel the operation, in which case `error` (if non-`None`) will be set to `IOErrorEnum::Cancelled`. If you are planning to connect to the service, it is usually easier to create a `NetworkService` and use its `SocketConnectable` interface. ## `service` the service type to look up (eg, "ldap") ## `protocol` the networking protocol to use for `service` (eg, "tcp") ## `domain` the DNS domain to look up the service in ## `cancellable` a `Cancellable`, or `None` # Returns a non-empty `glib::List` of `SrvTarget`, or `None` on error. You must free each of the targets and the list when you are done with it. (You can use `Resolver::free_targets` to do this.) Begins asynchronously performing a DNS SRV lookup for the given `service` and `protocol` in the given `domain`, and eventually calls `callback`, which must call `ResolverExt::lookup_service_finish` to get the final result. See `ResolverExt::lookup_service` for more details. ## `service` the service type to look up (eg, "ldap") ## `protocol` the networking protocol to use for `service` (eg, "tcp") ## `domain` the DNS domain to look up the service in ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call after resolution completes ## `user_data` data for `callback` Retrieves the result of a previous call to `ResolverExt::lookup_service_async`. If the DNS resolution failed, `error` (if non-`None`) will be set to a value from `ResolverError`. If the operation was cancelled, `error` will be set to `IOErrorEnum::Cancelled`. ## `result` the result passed to your `GAsyncReadyCallback` # Returns a non-empty `glib::List` of `SrvTarget`, or `None` on error. See `ResolverExt::lookup_service` for more details. Sets `self` to be the application's default resolver (reffing `self`, and unreffing the previous default resolver, if any). Future calls to `Resolver::get_default` will return this resolver. This can be used if an application wants to perform any sort of DNS caching or "pinning"; it can implement its own `Resolver` that calls the original default resolver for DNS operations, and implements its own cache policies on top of that, and then set itself as the default resolver for all later code to use. Emitted when the resolver notices that the system resolver configuration has changed. The type of record that `ResolverExt::lookup_records` or `ResolverExt::lookup_records_async` should retrieve. The records are returned as lists of `glib::Variant` tuples. Each record type has different values in the variant tuples returned. `ResolverRecordType::Srv` records are returned as variants with the signature '(qqqs)', containing a guint16 with the priority, a guint16 with the weight, a guint16 with the port, and a string of the hostname. `ResolverRecordType::Mx` records are returned as variants with the signature '(qs)', representing a guint16 with the preference, and a string containing the mail exchanger hostname. `ResolverRecordType::Txt` records are returned as variants with the signature '(as)', representing an array of the strings in the text record. `ResolverRecordType::Soa` records are returned as variants with the signature '(ssuuuuu)', representing a string containing the primary name server, a string containing the administrator, the serial as a guint32, the refresh interval as guint32, the retry interval as a guint32, the expire timeout as a guint32, and the ttl as a guint32. `ResolverRecordType::Ns` records are returned as variants with the signature '(s)', representing a string of the hostname of the name server. lookup DNS SRV records for a domain lookup DNS MX records for a domain lookup DNS TXT records for a name lookup DNS SOA records for a zone lookup DNS NS records for a domain Applications and libraries often contain binary or textual data that is really part of the application, rather than user data. For instance ``GtkBuilder`` .ui files, splashscreen images, GMenu markup XML, CSS files, icons, etc. These are often shipped as files in `$datadir/appname`, or manually included as literal strings in the code. The `Resource` API and the [glib-compile-resources][glib-compile-resources] program provide a convenient and efficient alternative to this which has some nice properties. You maintain the files as normal files, so its easy to edit them, but during the build the files are combined into a binary bundle that is linked into the executable. This means that loading the resource files are efficient (as they are already in memory, shared with other instances) and simple (no need to check for things like I/O errors or locate the files in the filesystem). It also makes it easier to create relocatable applications. Resource files can also be marked as compressed. Such files will be included in the resource bundle in a compressed form, but will be automatically uncompressed when the resource is used. This is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. Resource files can also be marked to be preprocessed, by setting the value of the `preprocess` attribute to a comma-separated list of preprocessing options. The only options currently supported are: `xml-stripblanks` which will use the xmllint command to strip ignorable whitespace from the XML file. For this to work, the `XMLLINT` environment variable must be set to the full path to the xmllint executable, or xmllint must be in the `PATH`; otherwise the preprocessing step is skipped. `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert images to the `GdkPixdata` format, which allows you to create pixbufs directly using the data inside the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will abort. Resource files will be exported in the GResource namespace using the combination of the given `prefix` and the filename from the `file` element. The `alias` attribute can be used to alter the filename to expose them at a different location in the resource namespace. Typically, this is used to include files from a different source directory without exposing the source directory in the resource namespace, as in the example below. Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program which takes an XML file that describes the bundle, and a set of files that the XML references. These are combined into a binary resource bundle. An example resource description: ```text data/splashscreen.png dialog.ui menumarkup.xml data/example.css ``` This will create a resource bundle with the following files: ```text /org/gtk/Example/data/splashscreen.png /org/gtk/Example/dialog.ui /org/gtk/Example/menumarkup.xml /org/gtk/Example/example.css ``` Note that all resources in the process share the same namespace, so use Java-style path prefixes (like in the above example) to avoid conflicts. You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a binary bundle that you can load with `Resource::load`. However, its more common to use the --generate-source and --generate-header arguments to create a source file and header to link directly into your application. This will generate `get_resource()`, `register_resource()` and `unregister_resource()` functions, prefixed by the `--c-name` argument passed to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns the generated `Resource` object. The register and unregister functions register the resource so its files can be accessed using `g_resources_lookup_data`. Once a `Resource` has been created and registered all the data in it can be accessed globally in the process by using API calls like `g_resources_open_stream` to stream the data or `g_resources_lookup_data` to get a direct pointer to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with `File` to access the resource data. Some higher-level APIs, such as ``GtkApplication``, will automatically load resources from certain well-known paths in the resource namespace as a convenience. See the documentation for those APIs for details. There are two forms of the generated source, the default version uses the compiler support for constructor and destructor functions (where available) to automatically create and register the `Resource` on startup or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created instead. This requires an explicit initialization call in your application/library, but it works on all platforms, even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses are for your own resources, and resource data is often used once, during parsing, and then released. When debugging a program or testing a change to an installed version, it is often useful to be able to replace resources in the program or library, without recompiling, for debugging or quick hacking and testing purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay resources with replacements from the filesystem. It is a colon-separated list of substitutions to perform during resource lookups. A substitution has the form ```text /org/gtk/libgtk=/home/desrt/gtk-overlay ``` The part before the `=` is the resource subpath for which the overlay applies. The part after is a filesystem path which contains files and subdirectories as you would like to be loaded as resources with the equivalent names. In the example above, if an application tried to load a resource with the resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an overlay, not an outright replacement, which means that if a file is not found at that path, the built-in version will be used instead. Whiteouts are not currently supported. Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the location of a single resource with an individual file. Creates a GResource from a reference to the binary resource bundle. This will keep a reference to `data` while the resource lives, so the data should not be modified or freed. If you want to use this resource in the global resource namespace you need to register it with `g_resources_register`. Note: `data` must be backed by memory that is at least pointer aligned. Otherwise this function will internally create a copy of the memory since GLib 2.56, or in older versions fail and exit the process. If `data` is empty or corrupt, `ResourceError::Internal` will be returned. ## `data` A `glib::Bytes` # Returns a new `Resource`, or `None` on error Returns all the names of children at the specified `path` in the resource. The return result is a `None` terminated list of strings which should be released with `g_strfreev`. If `path` is invalid or does not exist in the `Resource`, `ResourceError::NotFound` will be returned. `lookup_flags` controls the behaviour of the lookup. ## `path` A pathname inside the resource ## `lookup_flags` A `ResourceLookupFlags` # Returns an array of constant strings Looks for a file at the specified `path` in the resource and if found returns information about it. `lookup_flags` controls the behaviour of the lookup. ## `path` A pathname inside the resource ## `lookup_flags` A `ResourceLookupFlags` ## `size` a location to place the length of the contents of the file, or `None` if the length is not needed ## `flags` a location to place the flags about the file, or `None` if the length is not needed # Returns `true` if the file was found. `false` if there were errors Looks for a file at the specified `path` in the resource and returns a `glib::Bytes` that lets you directly access the data in memory. The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte is not included in the size of the GBytes. For uncompressed resource files this is a pointer directly into the resource bundle, which is typically in some readonly data section in the program binary. For compressed files we allocate memory on the heap and automatically uncompress the data. `lookup_flags` controls the behaviour of the lookup. ## `path` A pathname inside the resource ## `lookup_flags` A `ResourceLookupFlags` # Returns `glib::Bytes` or `None` on error. Free the returned object with `glib::Bytes::unref` Looks for a file at the specified `path` in the resource and returns a `InputStream` that lets you read the data. `lookup_flags` controls the behaviour of the lookup. ## `path` A pathname inside the resource ## `lookup_flags` A `ResourceLookupFlags` # Returns `InputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref` Atomically increments the reference count of `self` by one. This function is MT-safe and may be called from any thread. # Returns The passed in `Resource` Atomically decrements the reference count of `self` by one. If the reference count drops to 0, all memory allocated by the resource is released. This function is MT-safe and may be called from any thread. Loads a binary resource bundle and creates a `Resource` representation of it, allowing you to query it for data. If you want to use this resource in the global resource namespace you need to register it with `g_resources_register`. If `filename` is empty or the data in it is corrupt, `ResourceError::Internal` will be returned. If `filename` doesn’t exist, or there is an error in reading it, an error from `glib::MappedFile::new` will be returned. ## `filename` the path of a filename to load, in the GLib filename encoding # Returns a new `Resource`, or `None` on error An error code used with `G_RESOURCE_ERROR` in a `glib::Error` returned from a `Resource` routine. no file was found at the requested path unknown error `Seekable` is implemented by streams (implementations of `InputStream` or `OutputStream`) that support seeking. Seekable streams largely fall into two categories: resizable and fixed-size. `Seekable` on fixed-sized streams is approximately the same as POSIX `lseek` on a block device (for example: attmepting to seek past the end of the device is an error). Fixed streams typically cannot be truncated. `Seekable` on resizable streams is approximately the same as POSIX `lseek` on a normal file. Seeking past the end and writing data will usually cause the stream to resize by introducing zero bytes. # Implements [`SeekableExt`](trait.SeekableExt.html) Trait containing all `Seekable` methods. # Implementors [`BufferedInputStream`](struct.BufferedInputStream.html), [`BufferedOutputStream`](struct.BufferedOutputStream.html), [`DataInputStream`](struct.DataInputStream.html), [`DataOutputStream`](struct.DataOutputStream.html), [`FileIOStream`](struct.FileIOStream.html), [`FileInputStream`](struct.FileInputStream.html), [`FileOutputStream`](struct.FileOutputStream.html), [`MemoryInputStream`](struct.MemoryInputStream.html), [`MemoryOutputStream`](struct.MemoryOutputStream.html), [`Seekable`](struct.Seekable.html) Tests if the stream supports the `SeekableIface`. # Returns `true` if `self` can be seeked. `false` otherwise. Tests if the length of the stream can be adjusted with `Seekable::truncate`. # Returns `true` if the stream can be truncated, `false` otherwise. Seeks in the stream by the given `offset`, modified by `type_`. Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If the stream is resizable then seeking past the end and then writing will result in zeros filling the empty space. Seeking past the end of a resizable stream and reading will result in EOF. Seeking past the end of a fixed-sized stream will fail. Any operation that would result in a negative offset will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `offset` a `goffset`. ## `type_` a `glib::SeekType`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if successful. If an error has occurred, this function will return `false` and set `error` appropriately if present. Tells the current position within the stream. # Returns the offset from the beginning of the buffer. Sets the length of the stream to `offset`. If the stream was previously larger than `offset`, the extra data is discarded. If the stream was previouly shorter than `offset`, it is extended with NUL ('\0') bytes. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. ## `offset` new length for `self`, in bytes. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` if successful. If an error has occurred, this function will return `false` and set `error` appropriately if present. The `Settings` class provides a convenient API for storing and retrieving application settings. Reads and writes can be considered to be non-blocking. Reading settings with `Settings` is typically extremely fast: on approximately the same order of magnitude (but slower than) a `glib::HashTable` lookup. Writing settings is also extremely fast in terms of time to return to your application, but can be extremely expensive for other threads and other processes. Many settings backends (including dconf) have lazy initialisation which means in the common case of the user using their computer without modifying any settings a lot of work can be avoided. For dconf, the D-Bus service doesn't even need to be started in this case. For this reason, you should only ever modify `Settings` keys in response to explicit user action. Particular care should be paid to ensure that modifications are not made during startup -- for example, when setting the initial value of preferences widgets. The built-in `SettingsExt::bind` functionality is careful not to write settings in response to notify signals as a result of modifications that it makes to widgets. When creating a GSettings instance, you have to specify a schema that describes the keys in your settings and their types and default values, as well as some other information. Normally, a schema has a fixed path that determines where the settings are stored in the conceptual global tree of settings. However, schemas can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with a fixed path. This is useful e.g. when the schema describes an 'account', and you want to be able to store a arbitrary number of accounts. Paths must start with and end with a forward slash character ('/') and must not contain two sequential slash characters. Paths should be chosen based on a domain name associated with the program or library to which the settings belong. Examples of paths are "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/". Paths should not start with "/apps/", "/desktop/" or "/system/" as they often did in GConf. Unlike other configuration systems (like GConf), GSettings does not restrict keys to basic types like strings and numbers. GSettings stores values as `glib::Variant`, and allows any `glib::VariantType` for keys. Key names are restricted to lowercase characters, numbers and '-'. Furthermore, the names must begin with a lowercase character, must not end with a '-', and must not contain consecutive dashes. Similar to GConf, the default values in GSettings schemas can be localized, but the localized values are stored in gettext catalogs and looked up with the domain that is specified in the `gettext-domain` attribute of the `` or `` elements and the category that is specified in the `l10n` attribute of the `` element. The string which is translated includes all text in the `` element, including any surrounding quotation marks. The `l10n` attribute must be set to `messages` or `time`, and sets the [locale category for translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html`index`-locale-categories-1). The `messages` category should be used by default; use `time` for translatable date or time formats. A translation comment can be added as an XML comment immediately above the `` element — it is recommended to add these comments to aid translators understand the meaning and implications of the default value. An optional translation `context` attribute can be set on the `` element to disambiguate multiple defaults which use the same string. For example: ```text ['bad', 'words'] ``` Translations of default values must remain syntactically valid serialized `GVariants` (e.g. retaining any surrounding quotation marks) or runtime errors will occur. GSettings uses schemas in a compact binary form that is created by the [glib-compile-schemas][glib-compile-schemas] utility. The input is a schema description in an XML format. A DTD for the gschema XML format can be found here: [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd) The [glib-compile-schemas][glib-compile-schemas] tool expects schema files to have the extension `.gschema.xml`. At runtime, schemas are identified by their id (as specified in the id attribute of the `` element). The convention for schema ids is to use a dotted name, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular, if the settings are for a specific service that owns a D-Bus bus name, the D-Bus bus name and schema id should match. For schemas which deal with settings not associated with one named application, the id should not use StudlyCaps, e.g. "org.gnome.font-rendering". In addition to `glib::Variant` types, keys can have types that have enumerated types. These can be described by a ``, `` or `` element, as seen in the [example][schema-enumerated]. The underlying type of such a key is string, but you can use `SettingsExt::get_enum`, `SettingsExt::set_enum`, `SettingsExt::get_flags`, `SettingsExt::set_flags` access the numeric values corresponding to the string value of enum and flags keys. An example for default value: ```text "Hello, earthlings" A greeting Greeting of the invading martians (20,30) ``` An example for ranges, choices and enumerated types: ```text 10 'Joe' 'first' ["flag1","flag2"] ``` ## Vendor overrides Default values are defined in the schemas that get installed by an application. Sometimes, it is necessary for a vendor or distributor to adjust these defaults. Since patching the XML source for the schema is inconvenient and error-prone, [glib-compile-schemas][glib-compile-schemas] reads so-called vendor override' files. These are keyfiles in the same directory as the XML schema sources which can override default values. The schema id serves as the group name in the key file, and the values are expected in serialized GVariant form, as in the following example: ```text [org.gtk.Example] key1='string' key2=1.5 ``` glib-compile-schemas expects schema files to have the extension `.gschema.override`. ## Binding A very convenient feature of GSettings lets you bind `gobject::Object` properties directly to settings, using `SettingsExt::bind`. Once a GObject property has been bound to a setting, changes on either side are automatically propagated to the other side. GSettings handles details like mapping between GObject and GVariant types, and preventing infinite cycles. This makes it very easy to hook up a preferences dialog to the underlying settings. To make this even more convenient, GSettings looks for a boolean property with the name "sensitivity" and automatically binds it to the writability of the bound setting. If this 'magic' gets in the way, it can be suppressed with the `SettingsBindFlags::NoSensitivity` flag. ## Relocatable schemas # {`gsettings`-relocatable} A relocatable schema is one with no `path` attribute specified on its `` element. By using `Settings::new_with_path`, a `Settings` object can be instantiated for a relocatable schema, assigning a path to the instance. Paths passed to `Settings::new_with_path` will typically be constructed dynamically from a constant prefix plus some form of instance identifier; but they must still be valid GSettings paths. Paths could also be constant and used with a globally installed schema originating from a dependency library. For example, a relocatable schema could be used to store geometry information for different windows in an application. If the schema ID was `org.foo.MyApp.Window`, it could be instantiated for paths `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`, `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known they can be specified as `` elements in the parent schema, e.g.: ```text ``` ## Build system integration # {`gsettings`-build-system} GSettings comes with autotools integration to simplify compiling and installing schemas. To add GSettings support to an application, add the following to your `configure.ac`: ```text GLIB_GSETTINGS ``` In the appropriate `Makefile.am`, use the following snippet to compile and install the named schema: ```text gsettings_SCHEMAS = org.foo.MyApp.gschema.xml EXTRA_DIST = $(gsettings_SCHEMAS) @GSETTINGS_RULES@ ``` No changes are needed to the build system to mark a schema XML file for translation. Assuming it sets the `gettext-domain` attribute, a schema may be marked for translation by adding it to `POTFILES.in`, assuming gettext 0.19 is in use (the preferred method for translation): ```text data/org.foo.MyApp.gschema.xml ``` Alternatively, if intltool 0.50.1 is in use: ```text [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml ``` GSettings will use gettext to look up translations for the `` and `` elements, and also any `` elements which have a `l10n` attribute set. Translations must not be included in the `.gschema.xml` file by the build system, for example by using intltool XML rules with a `.gschema.xml.in` template. If an enumerated type defined in a C header file is to be used in a GSettings schema, it can either be defined manually using an `` element in the schema XML, or it can be extracted automatically from the C header. This approach is preferred, as it ensures the two representations are always synchronised. To do so, add the following to the relevant `Makefile.am`: ```text gsettings_ENUM_NAMESPACE = org.foo.MyApp gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h ``` `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files, which are specified in `gsettings_ENUM_FILES`. This will generate a `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be automatically included in the schema compilation, install and uninstall rules. It should not be committed to version control or included in `EXTRA_DIST`. # Implements [`SettingsExt`](trait.SettingsExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Settings` methods. # Implementors [`Settings`](struct.Settings.html) Creates a new `Settings` object with the schema specified by `schema_id`. Signals on the newly created `Settings` object will be dispatched via the thread-default `glib::MainContext` in effect at the time of the call to `Settings::new`. The new `Settings` will hold a reference on the context. See `glib::MainContext::push_thread_default`. ## `schema_id` the id of the schema # Returns a new `Settings` object Creates a new `Settings` object with a given schema, backend and path. It should be extremely rare that you ever want to use this function. It is made available for advanced use-cases (such as plugin systems that want to provide access to schemas loaded from custom locations, etc). At the most basic level, a `Settings` object is a pure composition of 4 things: a `SettingsSchema`, a `SettingsBackend`, a path within that backend, and a `glib::MainContext` to which signals are dispatched. This constructor therefore gives you full control over constructing `Settings` instances. The first 3 parameters are given directly as `schema`, `backend` and `path`, and the main context is taken from the thread-default (as per `Settings::new`). If `backend` is `None` then the default backend is used. If `path` is `None` then the path from the schema is used. It is an error if `path` is `None` and the schema has no path of its own or if `path` is non-`None` and not equal to the path that the schema does have. ## `schema` a `SettingsSchema` ## `backend` a `SettingsBackend` ## `path` the path to use # Returns a new `Settings` object Creates a new `Settings` object with the schema specified by `schema_id` and a given `SettingsBackend`. Creating a `Settings` object with a different backend allows accessing settings from a database other than the usual one. For example, it may make sense to pass a backend corresponding to the "defaults" settings database on the system to get a settings object that modifies the system default settings instead of the settings for this user. ## `schema_id` the id of the schema ## `backend` the `SettingsBackend` to use # Returns a new `Settings` object Creates a new `Settings` object with the schema specified by `schema_id` and a given `SettingsBackend` and path. This is a mix of `Settings::new_with_backend` and `Settings::new_with_path`. ## `schema_id` the id of the schema ## `backend` the `SettingsBackend` to use ## `path` the path to use # Returns a new `Settings` object Creates a new `Settings` object with the relocatable schema specified by `schema_id` and a given path. You only need to do this if you want to directly create a settings object with a schema that doesn't have a specified path of its own. That's quite rare. It is a programmer error to call this function for a schema that has an explicitly specified path. It is a programmer error if `path` is not a valid path. A valid path begins and ends with '/' and does not contain two consecutive '/' characters. ## `schema_id` the id of the schema ## `path` the path to use # Returns a new `Settings` object Ensures that all pending operations are complete for the default backend. Writes made to a `Settings` are handled asynchronously. For this reason, it is very unlikely that the changes have it to disk by the time `SettingsExt::set` returns. This call will block until all of the writes have made it to the backend. Since the mainloop is not running, no change notifications will be dispatched during this call (but some may be queued by the time the call is done). Removes an existing binding for `property` on `object`. Note that bindings are automatically removed when the object is finalized, so it is rarely necessary to call this function. ## `object` the object ## `property` the property whose binding is removed Applies any changes that have been made to the settings. This function does nothing unless `self` is in 'delay-apply' mode; see `SettingsExt::delay`. In the normal case settings are always applied immediately. Create a binding between the `key` in the `self` object and the property `property` of `object`. The binding uses the default GIO mapping functions to map between the settings and property values. These functions handle booleans, numeric types and string types in a straightforward way. Use `SettingsExt::bind_with_mapping` if you need a custom mapping, or map between types that are not supported by the default mapping functions. Unless the `flags` include `SettingsBindFlags::NoSensitivity`, this function also establishes a binding between the writability of `key` and the "sensitive" property of `object` (if `object` has a boolean property by that name). See `SettingsExt::bind_writable` for more details about writable bindings. Note that the lifecycle of the binding is tied to `object`, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. ## `key` the key to bind ## `object` a `gobject::Object` ## `property` the name of the property to bind ## `flags` flags for the binding Create a binding between the `key` in the `self` object and the property `property` of `object`. The binding uses the provided mapping functions to map between settings and property values. Note that the lifecycle of the binding is tied to `object`, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. ## `key` the key to bind ## `object` a `gobject::Object` ## `property` the name of the property to bind ## `flags` flags for the binding ## `get_mapping` a function that gets called to convert values from `self` to `object`, or `None` to use the default GIO mapping ## `set_mapping` a function that gets called to convert values from `object` to `self`, or `None` to use the default GIO mapping ## `user_data` data that gets passed to `get_mapping` and `set_mapping` ## `destroy` `GDestroyNotify` function for `user_data` Create a binding between the writability of `key` in the `self` object and the property `property` of `object`. The property must be boolean; "sensitive" or "visible" properties of widgets are the most likely candidates. Writable bindings are always uni-directional; changes of the writability of the setting will be propagated to the object property, not the other way. When the `inverted` argument is `true`, the binding inverts the value as it passes from the setting to the object, i.e. `property` will be set to `true` if the key is not writable. Note that the lifecycle of the binding is tied to `object`, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one. ## `key` the key to bind ## `object` a `gobject::Object` ## `property` the name of a boolean property to bind ## `inverted` whether to 'invert' the value Creates a `Action` corresponding to a given `Settings` key. The action has the same name as the key. The value of the key becomes the state of the action and the action is enabled when the key is writable. Changing the state of the action results in the key being written to. Changes to the value or writability of the key cause appropriate change notifications to be emitted for the action. For boolean-valued keys, action activations take no parameter and result in the toggling of the value. For all other types, activations take the new value for the key (which must have the correct type). ## `key` the name of a key in `self` # Returns a new `Action` Changes the `Settings` object into 'delay-apply' mode. In this mode, changes to `self` are not immediately propagated to the backend, but kept locally until `SettingsExt::apply` is called. Gets the value that is stored at `key` in `self`. A convenience function that combines `SettingsExt::get_value` with `glib::Variant::get`. It is a programmer error to give a `key` that isn't contained in the schema for `self` or for the `glib::VariantType` of `format` to mismatch the type given in the schema. ## `key` the key to get the value for ## `format` a `glib::Variant` format string Gets the value that is stored at `key` in `self`. A convenience variant of `SettingsExt::get` for booleans. It is a programmer error to give a `key` that isn't specified as having a boolean type in the schema for `self`. ## `key` the key to get the value for # Returns a boolean Creates a child settings object which has a base path of `base-path/@name`, where `base-path` is the base path of `self`. The schema for the child settings object must have been declared in the schema of `self` using a `` element. ## `name` the name of the child schema # Returns a 'child' settings object Gets the "default value" of a key. This is the value that would be read if `SettingsExt::reset` were to be called on the key. Note that this may be a different value than returned by `SettingsSchemaKey::get_default_value` if the system administrator has provided a default value. Comparing the return values of `SettingsExt::get_default_value` and `SettingsExt::get_value` is not sufficient for determining if a value has been set because the user may have explicitly set the value to something that happens to be equal to the default. The difference here is that if the default changes in the future, the user's key will still be set. This function may be useful for adding an indication to a UI of what the default value was before the user set it. It is a programmer error to give a `key` that isn't contained in the schema for `self`. ## `key` the key to get the default value for # Returns the default value Gets the value that is stored at `key` in `self`. A convenience variant of `SettingsExt::get` for doubles. It is a programmer error to give a `key` that isn't specified as having a 'double' type in the schema for `self`. ## `key` the key to get the value for # Returns a double Gets the value that is stored in `self` for `key` and converts it to the enum value that it represents. In order to use this function the type of the value must be a string and it must be marked in the schema file as an enumerated type. It is a programmer error to give a `key` that isn't contained in the schema for `self` or is not marked as an enumerated type. If the value stored in the configuration database is not a valid value for the enumerated type then this function will return the default value. ## `key` the key to get the value for # Returns the enum value Gets the value that is stored in `self` for `key` and converts it to the flags value that it represents. In order to use this function the type of the value must be an array of strings and it must be marked in the schema file as an flags type. It is a programmer error to give a `key` that isn't contained in the schema for `self` or is not marked as a flags type. If the value stored in the configuration database is not a valid value for the flags type then this function will return the default value. ## `key` the key to get the value for # Returns the flags value Returns whether the `Settings` object has any unapplied changes. This can only be the case if it is in 'delayed-apply' mode. # Returns `true` if `self` has unapplied changes Gets the value that is stored at `key` in `self`. A convenience variant of `SettingsExt::get` for 32-bit integers. It is a programmer error to give a `key` that isn't specified as having a int32 type in the schema for `self`. ## `key` the key to get the value for # Returns an integer Gets the value that is stored at `key` in `self`. A convenience variant of `SettingsExt::get` for 64-bit integers. It is a programmer error to give a `key` that isn't specified as having a int64 type in the schema for `self`. Feature: `v2_50` ## `key` the key to get the value for # Returns a 64-bit integer Gets the value that is stored at `key` in `self`, subject to application-level validation/mapping. You should use this function when the application needs to perform some processing on the value of the key (for example, parsing). The `mapping` function performs that processing. If the function indicates that the processing was unsuccessful (due to a parse error, for example) then the mapping is tried again with another value. This allows a robust 'fall back to defaults' behaviour to be implemented somewhat automatically. The first value that is tried is the user's setting for the key. If the mapping function fails to map this value, other values may be tried in an unspecified order (system or site defaults, translated schema default values, untranslated schema default values, etc). If the mapping function fails for all possible values, one additional attempt is made: the mapping function is called with a `None` value. If the mapping function still indicates failure at this point then the application will be aborted. The result parameter for the `mapping` function is pointed to a `gpointer` which is initially set to `None`. The same pointer is given to each invocation of `mapping`. The final value of that `gpointer` is what is returned by this function. `None` is valid; it is returned just as any other value would be. ## `key` the key to get the value for ## `mapping` the function to map the value in the settings database to the value used by the application ## `user_data` user data for `mapping` # Returns the result, which may be `None` Gets the value that is stored at `key` in `self`. A convenience variant of `SettingsExt::get` for strings. It is a programmer error to give a `key` that isn't specified as having a string type in the schema for `self`. ## `key` the key to get the value for # Returns a newly-allocated string A convenience variant of `SettingsExt::get` for string arrays. It is a programmer error to give a `key` that isn't specified as having an array of strings type in the schema for `self`. ## `key` the key to get the value for # Returns a newly-allocated, `None`-terminated array of strings, the value that is stored at `key` in `self`. Gets the value that is stored at `key` in `self`. A convenience variant of `SettingsExt::get` for 32-bit unsigned integers. It is a programmer error to give a `key` that isn't specified as having a uint32 type in the schema for `self`. ## `key` the key to get the value for # Returns an unsigned integer Gets the value that is stored at `key` in `self`. A convenience variant of `SettingsExt::get` for 64-bit unsigned integers. It is a programmer error to give a `key` that isn't specified as having a uint64 type in the schema for `self`. Feature: `v2_50` ## `key` the key to get the value for # Returns a 64-bit unsigned integer Checks the "user value" of a key, if there is one. The user value of a key is the last value that was set by the user. After calling `SettingsExt::reset` this function should always return `None` (assuming something is not wrong with the system configuration). It is possible that `SettingsExt::get_value` will return a different value than this function. This can happen in the case that the user set a value for a key that was subsequently locked down by the system administrator -- this function will return the user's old value. This function may be useful for adding a "reset" option to a UI or for providing indication that a particular value has been changed. It is a programmer error to give a `key` that isn't contained in the schema for `self`. ## `key` the key to get the user value for # Returns the user's value, if set Gets the value that is stored in `self` for `key`. It is a programmer error to give a `key` that isn't contained in the schema for `self`. ## `key` the key to get the value for # Returns a new `glib::Variant` Finds out if a key can be written or not ## `name` the name of a key # Returns `true` if the key `name` is writable Gets the list of children on `self`. The list is exactly the list of strings for which it is not an error to call `SettingsExt::get_child`. For GSettings objects that are lists, this value can change at any time. Note that there is a race condition here: you may request a child after listing it only for it to have been destroyed in the meantime. For this reason, `SettingsExt::get_child` may return `None` even for a child that was listed by this function. For GSettings objects that are not lists, you should probably not be calling this function from "normal" code (since you should already know what children are in your schema). This function may still be useful there for introspection reasons, however. You should free the return value with `g_strfreev` when you are done with it. # Returns a list of the children on `self` Introspects the list of keys on `self`. You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This function is intended for introspection reasons. You should free the return value with `g_strfreev` when you are done with it. # Returns a list of the keys on `self` Resets `key` to its default value. This call resets the key, as much as possible, to its default value. That might the value specified in the schema or the one set by the administrator. ## `key` the name of a key Reverts all non-applied changes to the settings. This function does nothing unless `self` is in 'delay-apply' mode; see `SettingsExt::delay`. In the normal case settings are always applied immediately. Change notifications will be emitted for affected keys. Sets `key` in `self` to `value`. A convenience function that combines `SettingsExt::set_value` with `glib::Variant::new`. It is a programmer error to give a `key` that isn't contained in the schema for `self` or for the `glib::VariantType` of `format` to mismatch the type given in the schema. ## `key` the name of the key to set ## `format` a `glib::Variant` format string # Returns `true` if setting the key succeeded, `false` if the key was not writable Sets `key` in `self` to `value`. A convenience variant of `SettingsExt::set` for booleans. It is a programmer error to give a `key` that isn't specified as having a boolean type in the schema for `self`. ## `key` the name of the key to set ## `value` the value to set it to # Returns `true` if setting the key succeeded, `false` if the key was not writable Sets `key` in `self` to `value`. A convenience variant of `SettingsExt::set` for doubles. It is a programmer error to give a `key` that isn't specified as having a 'double' type in the schema for `self`. ## `key` the name of the key to set ## `value` the value to set it to # Returns `true` if setting the key succeeded, `false` if the key was not writable Looks up the enumerated type nick for `value` and writes it to `key`, within `self`. It is a programmer error to give a `key` that isn't contained in the schema for `self` or is not marked as an enumerated type, or for `value` not to be a valid value for the named type. After performing the write, accessing `key` directly with `SettingsExt::get_string` will return the 'nick' associated with `value`. ## `key` a key, within `self` ## `value` an enumerated value # Returns `true`, if the set succeeds Looks up the flags type nicks for the bits specified by `value`, puts them in an array of strings and writes the array to `key`, within `self`. It is a programmer error to give a `key` that isn't contained in the schema for `self` or is not marked as a flags type, or for `value` to contain any bits that are not value for the named type. After performing the write, accessing `key` directly with `SettingsExt::get_strv` will return an array of 'nicks'; one for each bit in `value`. ## `key` a key, within `self` ## `value` a flags value # Returns `true`, if the set succeeds Sets `key` in `self` to `value`. A convenience variant of `SettingsExt::set` for 32-bit integers. It is a programmer error to give a `key` that isn't specified as having a int32 type in the schema for `self`. ## `key` the name of the key to set ## `value` the value to set it to # Returns `true` if setting the key succeeded, `false` if the key was not writable Sets `key` in `self` to `value`. A convenience variant of `SettingsExt::set` for 64-bit integers. It is a programmer error to give a `key` that isn't specified as having a int64 type in the schema for `self`. Feature: `v2_50` ## `key` the name of the key to set ## `value` the value to set it to # Returns `true` if setting the key succeeded, `false` if the key was not writable Sets `key` in `self` to `value`. A convenience variant of `SettingsExt::set` for strings. It is a programmer error to give a `key` that isn't specified as having a string type in the schema for `self`. ## `key` the name of the key to set ## `value` the value to set it to # Returns `true` if setting the key succeeded, `false` if the key was not writable Sets `key` in `self` to `value`. A convenience variant of `SettingsExt::set` for string arrays. If `value` is `None`, then `key` is set to be the empty array. It is a programmer error to give a `key` that isn't specified as having an array of strings type in the schema for `self`. ## `key` the name of the key to set ## `value` the value to set it to, or `None` # Returns `true` if setting the key succeeded, `false` if the key was not writable Sets `key` in `self` to `value`. A convenience variant of `SettingsExt::set` for 32-bit unsigned integers. It is a programmer error to give a `key` that isn't specified as having a uint32 type in the schema for `self`. ## `key` the name of the key to set ## `value` the value to set it to # Returns `true` if setting the key succeeded, `false` if the key was not writable Sets `key` in `self` to `value`. A convenience variant of `SettingsExt::set` for 64-bit unsigned integers. It is a programmer error to give a `key` that isn't specified as having a uint64 type in the schema for `self`. Feature: `v2_50` ## `key` the name of the key to set ## `value` the value to set it to # Returns `true` if setting the key succeeded, `false` if the key was not writable Sets `key` in `self` to `value`. It is a programmer error to give a `key` that isn't contained in the schema for `self` or for `value` to have the incorrect type, per the schema. If `value` is floating then this function consumes the reference. ## `key` the name of the key to set ## `value` a `glib::Variant` of the correct type # Returns `true` if setting the key succeeded, `false` if the key was not writable The "change-event" signal is emitted once per change event that affects this settings object. You should connect to this signal only if you are interested in viewing groups of changes before they are split out into multiple emissions of the "changed" signal. For most use cases it is more appropriate to use the "changed" signal. In the event that the change event applies to one or more specified keys, `keys` will be an array of `glib::Quark` of length `n_keys`. In the event that the change event applies to the `Settings` object as a whole (ie: potentially every key has been changed) then `keys` will be `None` and `n_keys` will be 0. The default handler for this signal invokes the "changed" signal for each affected key. If any other connected handler returns `true` then this default functionality will be suppressed. ## `keys` an array of `GQuarks` for the changed keys, or `None` ## `n_keys` the length of the `keys` array, or 0 # Returns `true` to stop other handlers from being invoked for the event. FALSE to propagate the event further. The "changed" signal is emitted when a key has potentially changed. You should call one of the `SettingsExt::get` calls to check the new value. This signal supports detailed connections. You can connect to the detailed signal "changed::x" in order to only receive callbacks when key "x" changes. Note that `settings` only emits this signal if you have read `key` at least once while a signal handler was already connected for `key`. ## `key` the name of the key that changed The "writable-change-event" signal is emitted once per writability change event that affects this settings object. You should connect to this signal if you are interested in viewing groups of changes before they are split out into multiple emissions of the "writable-changed" signal. For most use cases it is more appropriate to use the "writable-changed" signal. In the event that the writability change applies only to a single key, `key` will be set to the `glib::Quark` for that key. In the event that the writability change affects the entire settings object, `key` will be 0. The default handler for this signal invokes the "writable-changed" and "changed" signals for each affected key. This is done because changes in writability might also imply changes in value (if for example, a new mandatory setting is introduced). If any other connected handler returns `true` then this default functionality will be suppressed. ## `key` the quark of the key, or 0 # Returns `true` to stop other handlers from being invoked for the event. FALSE to propagate the event further. The "writable-changed" signal is emitted when the writability of a key has potentially changed. You should call `SettingsExt::is_writable` in order to determine the new status. This signal supports detailed connections. You can connect to the detailed signal "writable-changed::x" in order to only receive callbacks when the writability of "x" changes. ## `key` the key The name of the context that the settings are stored in. The name of the context that the settings are stored in. Whether the `Settings` object is in 'delay-apply' mode. See `SettingsExt::delay` for details. If this property is `true`, the `Settings` object has outstanding changes that will be applied when `SettingsExt::apply` is called. The path within the backend where the settings are stored. The path within the backend where the settings are stored. The name of the schema that describes the types of keys for this `Settings` object. The name of the schema that describes the types of keys for this `Settings` object. The `SettingsSchema` describing the types of keys for this `Settings` object. Ideally, this property would be called 'schema'. `SettingsSchema` has only existed since version 2.32, however, and before then the 'schema' property was used to refer to the ID of the schema rather than the schema itself. Take care. The `SettingsSchema` describing the types of keys for this `Settings` object. Ideally, this property would be called 'schema'. `SettingsSchema` has only existed since version 2.32, however, and before then the 'schema' property was used to refer to the ID of the schema rather than the schema itself. Take care. The `SettingsBackend` interface defines a generic interface for non-strictly-typed data that is stored in a hierarchy. To implement an alternative storage backend for `Settings`, you need to implement the `SettingsBackend` interface and then make it implement the extension point `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`. The interface defines methods for reading and writing values, a method for determining if writing of certain values will fail (lockdown) and a change notification mechanism. The semantics of the interface are very precisely defined and implementations must carefully adhere to the expectations of callers that are documented on each of the interface methods. Some of the `SettingsBackend` functions accept or return a `glib::Tree`. These trees always have strings as keys and `glib::Variant` as values. `g_settings_backend_create_tree` is a convenience function to create suitable trees. The `SettingsBackend` API is exported to allow third-party implementations, but does not carry the same stability guarantees as the public GIO API. For this reason, you have to define the C preprocessor symbol `G_SETTINGS_ENABLE_BACKEND` before including `gio/gsettingsbackend.h`. # Implements [`SettingsBackendExt`](trait.SettingsBackendExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `SettingsBackend` methods. # Implementors [`SettingsBackend`](struct.SettingsBackend.html) Calculate the longest common prefix of all keys in a tree and write out an array of the key names relative to that prefix and, optionally, the value to store at each of those keys. You must free the value returned in `path`, `keys` and `values` using `g_free`. You should not attempt to free or unref the contents of `keys` or `values`. ## `tree` a `glib::Tree` containing the changes ## `path` the location to save the path ## `keys` the location to save the relative keys ## `values` the location to save the values, or `None` Returns the default `SettingsBackend`. It is possible to override the default by setting the `GSETTINGS_BACKEND` environment variable to the name of a settings backend. The user gets a reference to the backend. # Returns the default `SettingsBackend` Signals that a single key has possibly changed. Backend implementations should call this if a key has possibly changed its value. `key` must be a valid key (ie starting with a slash, not containing '//', and not ending with a slash). The implementation must call this function during any call to `g_settings_backend_write`, before the call returns (except in the case that no keys are actually changed and it cares to detect this fact). It may not rely on the existence of a mainloop for dispatching the signal later. The implementation may call this function at any other time it likes in response to other events (such as changes occurring outside of the program). These calls may originate from a mainloop or may originate in response to any other action (including from calls to `g_settings_backend_write`). In the case that this call is in response to a call to `g_settings_backend_write` then `origin_tag` must be set to the same value that was passed to that call. ## `key` the name of the key ## `origin_tag` the origin tag This call is a convenience wrapper. It gets the list of changes from `tree`, computes the longest common prefix and calls `SettingsBackendExt::changed`. ## `tree` a `glib::Tree` containing the changes ## `origin_tag` the origin tag Signals that a list of keys have possibly changed. Backend implementations should call this if keys have possibly changed their values. `path` must be a valid path (ie starting and ending with a slash and not containing '//'). Each string in `items` must form a valid key name when `path` is prefixed to it (ie: each item must not start or end with '/' and must not contain '//'). The meaning of this signal is that any of the key names resulting from the contatenation of `path` with each item in `items` may have changed. The same rules for when notifications must occur apply as per `SettingsBackendExt::changed`. These two calls can be used interchangeably if exactly one item has changed (although in that case `SettingsBackendExt::changed` is definitely preferred). For efficiency reasons, the implementation should strive for `path` to be as long as possible (ie: the longest common prefix of all of the keys that were changed) but this is not strictly required. ## `path` the path containing the changes ## `items` the `None`-terminated list of changed keys ## `origin_tag` the origin tag Signals that all keys below a given path may have possibly changed. Backend implementations should call this if an entire path of keys have possibly changed their values. `path` must be a valid path (ie starting and ending with a slash and not containing '//'). The meaning of this signal is that any of the key which has a name starting with `path` may have changed. The same rules for when notifications must occur apply as per `SettingsBackendExt::changed`. This call might be an appropriate reasponse to a 'reset' call but implementations are also free to explicitly list the keys that were affected by that call if they can easily do so. For efficiency reasons, the implementation should strive for `path` to be as long as possible (ie: the longest common prefix of all of the keys that were changed) but this is not strictly required. As an example, if this function is called with the path of "/" then every single key in the application will be notified of a possible change. ## `path` the path containing the changes ## `origin_tag` the origin tag Signals that the writability of all keys below a given path may have changed. Since GSettings performs no locking operations for itself, this call will always be made in response to external events. ## `path` the name of the path Signals that the writability of a single key has possibly changed. Since GSettings performs no locking operations for itself, this call will always be made in response to external events. ## `key` the name of the key The `SettingsSchemaSource` and `SettingsSchema` APIs provide a mechanism for advanced control over the loading of schemas and a mechanism for introspecting their content. Plugin loading systems that wish to provide plugins a way to access settings face the problem of how to make the schemas for these settings visible to GSettings. Typically, a plugin will want to ship the schema along with itself and it won't be installed into the standard system directories for schemas. `SettingsSchemaSource` provides a mechanism for dealing with this by allowing the creation of a new 'schema source' from which schemas can be acquired. This schema source can then become part of the metadata associated with the plugin and queried whenever the plugin requires access to some settings. Consider the following example: ```C typedef struct { ... GSettingsSchemaSource *schema_source; ... } Plugin; Plugin * initialise_plugin (const gchar *dir) { Plugin *plugin; ... plugin->schema_source = g_settings_schema_source_new_from_directory (dir, g_settings_schema_source_get_default (), FALSE, NULL); ... return plugin; } ... GSettings * plugin_get_settings (Plugin *plugin, const gchar *schema_id) { GSettingsSchema *schema; if (schema_id == NULL) schema_id = plugin->identifier; schema = g_settings_schema_source_lookup (plugin->schema_source, schema_id, FALSE); if (schema == NULL) { ... disable the plugin or abort, etc ... } return g_settings_new_full (schema, NULL, NULL); } ``` The code above shows how hooks should be added to the code that initialises (or enables) the plugin to create the schema source and how an API can be added to the plugin system to provide a convenient way for the plugin to access its settings, using the schemas that it ships. From the standpoint of the plugin, it would need to ensure that it ships a gschemas.compiled file as part of itself, and then simply do the following: ```C { GSettings *settings; gint some_value; settings = plugin_get_settings (self, NULL); some_value = g_settings_get_int (settings, "some-value"); ... } ``` It's also possible that the plugin system expects the schema source files (ie: .gschema.xml files) instead of a gschemas.compiled file. In that case, the plugin loading system must compile the schemas for itself before attempting to create the settings source. Get the ID of `self`. # Returns the ID Gets the key named `name` from `self`. It is a programmer error to request a key that does not exist. See `SettingsSchema::list_keys`. ## `name` the name of a key # Returns the `SettingsSchemaKey` for `name` Gets the path associated with `self`, or `None`. Schemas may be single-instance or relocatable. Single-instance schemas correspond to exactly one set of keys in the backend database: those located at the path returned by this function. Relocatable schemas can be referenced by other schemas and can threfore describe multiple sets of keys at different locations. For relocatable schemas, this function will return `None`. # Returns the path of the schema, or `None` Checks if `self` has a key named `name`. ## `name` the name of a key # Returns `true` if such a key exists Gets the list of children in `self`. You should free the return value with `g_strfreev` when you are done with it. Feature: `v2_44` # Returns a list of the children on `settings` Introspects the list of keys on `self`. You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This function is intended for introspection reasons. Feature: `v2_46` # Returns a list of the keys on `self` Increase the reference count of `self`, returning a new reference. # Returns a new reference to `self` Decrease the reference count of `self`, possibly freeing it. `SettingsSchemaKey` is an opaque data structure and can only be accessed using the following functions. Gets the default value for `self`. Note that this is the default value according to the schema. System administrator defaults and lockdown are not visible via this API. # Returns the default value for the key Gets the description for `self`. If no description has been provided in the schema for `self`, returns `None`. The description can be one sentence to several paragraphs in length. Paragraphs are delimited with a double newline. Descriptions can be translated and the value returned from this function is is the current locale. This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. # Returns the description for `self`, or `None` Gets the name of `self`. Feature: `v2_44` # Returns the name of `self`. Queries the range of a key. This function will return a `glib::Variant` that fully describes the range of values that are valid for `self`. The type of `glib::Variant` returned is `(sv)`. The string describes the type of range restriction in effect. The type and meaning of the value contained in the variant depends on the string. If the string is `'type'` then the variant contains an empty array. The element type of that empty array is the expected type of value and all values of that type are valid. If the string is `'enum'` then the variant contains an array enumerating the possible values. Each item in the array is a possible valid value and no other values are valid. If the string is `'flags'` then the variant contains an array. Each item in the array is a value that may appear zero or one times in an array to be used as the value for this key. For example, if the variant contained the array `['x', 'y']` then the valid values for the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and `['y', 'x']`. Finally, if the string is `'range'` then the variant contains a pair of like-typed values -- the minimum and maximum permissible values for this key. This information should not be used by normal programs. It is considered to be a hint for introspection purposes. Normal programs should already know what is permitted by their own schema. The format may change in any way in the future -- but particularly, new forms may be added to the possibilities described above. You should free the returned value with `glib::Variant::unref` when it is no longer needed. # Returns a `glib::Variant` describing the range Gets the summary for `self`. If no summary has been provided in the schema for `self`, returns `None`. The summary is a short description of the purpose of the key; usually one short sentence. Summaries can be translated and the value returned from this function is is the current locale. This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. # Returns the summary for `self`, or `None` Gets the `glib::VariantType` of `self`. # Returns the type of `self` Checks if the given `value` is of the correct type and within the permitted range for `self`. It is a programmer error if `value` is not of the correct type -- you must check for this first. ## `value` the value to check # Returns `true` if `value` is valid for `self` Increase the reference count of `self`, returning a new reference. # Returns a new reference to `self` Decrease the reference count of `self`, possibly freeing it. This is an opaque structure type. You may not access it directly. Attempts to create a new schema source corresponding to the contents of the given directory. This function is not required for normal uses of `Settings` but it may be useful to authors of plugin management systems. The directory should contain a file called `gschemas.compiled` as produced by the [glib-compile-schemas][glib-compile-schemas] tool. If `trusted` is `true` then `gschemas.compiled` is trusted not to be corrupted. This assumption has a performance advantage, but can result in crashes or inconsistent behaviour in the case of a corrupted file. Generally, you should set `trusted` to `true` for files installed by the system and to `false` for files in the home directory. In either case, an empty file or some types of corruption in the file will result in `glib::FileError::Inval` being returned. If `parent` is non-`None` then there are two effects. First, if `SettingsSchemaSource::lookup` is called with the `recursive` flag set to `true` and the schema can not be found in the source, the lookup will recurse to the parent. Second, any references to other schemas specified within this source (ie: `child` or `extends`) references may be resolved from the `parent`. For this second reason, except in very unusual situations, the `parent` should probably be given as the default schema source, as returned by `SettingsSchemaSource::get_default`. ## `directory` the filename of a directory ## `parent` a `SettingsSchemaSource`, or `None` ## `trusted` `true`, if the directory is trusted Lists the schemas in a given source. If `recursive` is `true` then include parent sources. If `false` then only include the schemas from one source (ie: one directory). You probably want `true`. Non-relocatable schemas are those for which you can call `Settings::new`. Relocatable schemas are those for which you must use `Settings::new_with_path`. Do not call this function from normal programs. This is designed for use by database editors, commandline tools, etc. ## `recursive` if we should recurse ## `non_relocatable` the list of non-relocatable schemas ## `relocatable` the list of relocatable schemas Looks up a schema with the identifier `schema_id` in `self`. This function is not required for normal uses of `Settings` but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas. If the schema isn't found directly in `self` and `recursive` is `true` then the parent sources will also be checked. If the schema isn't found, `None` is returned. ## `schema_id` a schema ID ## `recursive` `true` if the lookup should be recursive # Returns a new `SettingsSchema` Increase the reference count of `self`, returning a new reference. # Returns a new reference to `self` Decrease the reference count of `self`, possibly freeing it. Gets the default system schema source. This function is not required for normal uses of `Settings` but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas. If no schemas are installed, `None` will be returned. The returned source may actually consist of multiple schema sources from different directories, depending on which directories were given in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all lookups performed against the default source should probably be done recursively. # Returns the default schema source A `SimpleAction` is the obvious simple implementation of the `Action` interface. This is the easiest way to create an action for purposes of adding it to a `SimpleActionGroup`. See also ``GtkAction``. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ActionExt`](trait.ActionExt.html) Creates a new action. The created action is stateless. See `SimpleAction::new_stateful` to create an action that has state. ## `name` the name of the action ## `parameter_type` the type of parameter that will be passed to handlers for the `SimpleAction::activate` signal, or `None` for no parameter # Returns a new `SimpleAction` Creates a new stateful action. All future state values must have the same `glib::VariantType` as the initial `state`. If the `state` `glib::Variant` is floating, it is consumed. ## `name` the name of the action ## `parameter_type` the type of the parameter that will be passed to handlers for the `SimpleAction::activate` signal, or `None` for no parameter ## `state` the initial state of the action # Returns a new `SimpleAction` Sets the action as enabled or not. An action must be enabled in order to be activated or in order to have its state changed from outside callers. This should only be called by the implementor of the action. Users of the action should not attempt to modify its enabled flag. ## `enabled` whether the action is enabled Sets the state of the action. This directly updates the 'state' property to the given value. This should only be called by the implementor of the action. Users of the action should not attempt to directly modify the 'state' property. Instead, they should call `Action::change_state` to request the change. If the `value` GVariant is floating, it is consumed. ## `value` the new `glib::Variant` for the state Sets the state hint for the action. See `Action::get_state_hint` for more information about action state hints. Feature: `v2_44` ## `state_hint` a `glib::Variant` representing the state hint Indicates that the action was just activated. `parameter` will always be of the expected type, i.e. the parameter type specified when the action was created. If an incorrect type is given when activating the action, this signal is not emitted. Since GLib 2.40, if no handler is connected to this signal then the default behaviour for boolean-stated actions with a `None` parameter type is to toggle them via the `SimpleAction::change-state` signal. For stateful actions where the state type is equal to the parameter type, the default is to forward them directly to `SimpleAction::change-state`. This should allow almost all users of `SimpleAction` to connect only one handler or the other. ## `parameter` the parameter to the activation, or `None` if it has no parameter Indicates that the action just received a request to change its state. `value` will always be of the correct state type, i.e. the type of the initial state passed to `SimpleAction::new_stateful`. If an incorrect type is given when requesting to change the state, this signal is not emitted. If no handler is connected to this signal then the default behaviour is to call `SimpleAction::set_state` to set the state to the requested value. If you connect a signal handler then no default action is taken. If the state should change then you must call `SimpleAction::set_state` from the handler. An example of a 'change-state' handler: ```C static void change_volume_state (GSimpleAction *action, GVariant *value, gpointer user_data) { gint requested; requested = g_variant_get_int32 (value); // Volume only goes from 0 to 10 if (0 <= requested && requested <= 10) g_simple_action_set_state (action, value); } ``` The handler need not set the state to the requested value. It could set it to any value at all, or take some other action. ## `value` the requested value for the state If `action` is currently enabled. If the action is disabled then calls to `Action::activate` and `Action::change_state` have no effect. If `action` is currently enabled. If the action is disabled then calls to `Action::activate` and `Action::change_state` have no effect. The name of the action. This is mostly meaningful for identifying the action once it has been added to a `SimpleActionGroup`. The name of the action. This is mostly meaningful for identifying the action once it has been added to a `SimpleActionGroup`. The type of the parameter that must be given when activating the action. The type of the parameter that must be given when activating the action. The state of the action, or `None` if the action is stateless. The state of the action, or `None` if the action is stateless. The `glib::VariantType` of the state that the action has, or `None` if the action is stateless. `SimpleActionGroup` is a hash table filled with `Action` objects, implementing the `ActionGroup` and `ActionMap` interfaces. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ActionGroupExt`](trait.ActionGroupExt.html), [`ActionMapExt`](trait.ActionMapExt.html) Creates a new, empty, `SimpleActionGroup`. # Returns a new `SimpleActionGroup` GSimpleIOStream creates a `IOStream` from an arbitrary `InputStream` and `OutputStream`. This allows any pair of input and output streams to be used with `IOStream` methods. This is useful when you obtained a `InputStream` and a `OutputStream` by other means, for instance creating them with platform specific methods as `UnixInputStream::new` or `g_win32_input_stream_new`, and you want to take advantage of the methods provided by `IOStream`. Feature: `v2_44` # Implements [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `SimpleIOStream` wrapping `input_stream` and `output_stream`. See also `IOStream`. Feature: `v2_44` ## `input_stream` a `InputStream`. ## `output_stream` a `OutputStream`. # Returns a new `SimpleIOStream` instance. `SimplePermission` is a trivial implementation of `Permission` that represents a permission that is either always or never allowed. The value is given at construction and doesn't change. Calling request or release will result in errors. # Implements [`PermissionExt`](trait.PermissionExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Permission` instance that represents an action that is either always or never allowed. ## `allowed` `true` if the action is allowed # Returns the `SimplePermission`, as a `Permission` A `Socket` is a low-level networking primitive. It is a more or less direct mapping of the BSD socket API in a portable GObject based API. It supports both the UNIX socket implementations and winsock2 on Windows. `Socket` is the platform independent base upon which the higher level network primitives are based. Applications are not typically meant to use it directly, but rather through classes like `SocketClient`, `SocketService` and `SocketConnection`. However there may be cases where direct use of `Socket` is useful. `Socket` implements the `Initable` interface, so if it is manually constructed by e.g. `gobject::Object::new` you must call `Initable::init` and check the results before using the object. This is done automatically in `Socket::new` and `Socket::new_from_fd`, so these functions can return `None`. Sockets operate in two general modes, blocking or non-blocking. When in blocking mode all operations (which don’t take an explicit blocking parameter) block until the requested operation is finished or there is an error. In non-blocking mode all calls that would block return immediately with a `IOErrorEnum::WouldBlock` error. To know when a call would successfully run you can call `SocketExt::condition_check`, or `SocketExt::condition_wait`. You can also use `Socket::create_source` and attach it to a `glib::MainContext` to get callbacks when I/O is possible. Note that all sockets are always set to non blocking mode in the system, and blocking mode is emulated in GSocket. When working in non-blocking mode applications should always be able to handle getting a `IOErrorEnum::WouldBlock` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write returns `IOErrorEnum::WouldBlock`. `GSockets` can be either connection oriented or datagram based. For connection oriented types you must first establish a connection by either connecting to an address or accepting a connection from another address. For connectionless socket types the target/source address is specified or received in each I/O operation. All socket file descriptors are set to be close-on-exec. Note that creating a `Socket` causes the signal `SIGPIPE` to be ignored for the remainder of the program. If you are writing a command-line utility that uses `Socket`, you may need to take into account the fact that your program will not automatically be killed if it tries to write to `stdout` after it has been closed. Like most other APIs in GLib, `Socket` is not inherently thread safe. To use a `Socket` concurrently from multiple threads, you must implement your own locking. # Implements [`SocketExt`](trait.SocketExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketExtManual`](prelude/trait.SocketExtManual.html) Trait containing all `Socket` methods. # Implementors [`Socket`](struct.Socket.html) Creates a new `Socket` with the defined family, type and protocol. If `protocol` is 0 (`SocketProtocol::Default`) the default protocol type for the family and type is used. The `protocol` is a family and type specific int that specifies what kind of protocol to use. `SocketProtocol` lists several common ones. Many families only support one protocol, and use 0 for this, others support several and using 0 means to use the default protocol for the family and type. The protocol id is passed directly to the operating system, so you can use protocols not listed in `SocketProtocol` if you know the protocol number used for it. ## `family` the socket family to use, e.g. `SocketFamily::Ipv4`. ## `type_` the socket type to use. ## `protocol` the id of the protocol to use, or 0 for default. # Returns a `Socket` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Creates a new `Socket` from a native file descriptor or winsock SOCKET handle. This reads all the settings from the file descriptor so that all properties should work. Note that the file descriptor will be set to non-blocking mode, independent on the blocking mode of the `Socket`. On success, the returned `Socket` takes ownership of `fd`. On failure, the caller must close `fd` themselves. Since GLib 2.46, it is no longer a fatal error to call this on a non-socket descriptor. Instead, a GError will be set with code `IOErrorEnum::Failed` ## `fd` a native socket file descriptor. # Returns a `Socket` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Accept incoming connections on a connection-based socket. This removes the first outstanding connection request from the listening socket and creates a `Socket` object for it. The `self` must be bound to a local address with `SocketExt::bind` and must be listening for incoming connections (`SocketExt::listen`). If there are no outstanding connections then the operation will block or return `IOErrorEnum::WouldBlock` if non-blocking I/O is enabled. To be notified of an incoming connection, wait for the `glib::IOCondition::In` condition. ## `cancellable` a `Cancellable` or `None` # Returns a new `Socket`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. When a socket is created it is attached to an address family, but it doesn't have an address in this family. `SocketExt::bind` assigns the address (sometimes called name) of the socket. It is generally required to bind to a local address before you can receive connections. (See `SocketExt::listen` and `SocketExt::accept` ). In certain situations, you may also want to bind a socket that will be used to initiate connections, though this is not normally required. If `self` is a TCP socket, then `allow_reuse` controls the setting of the `SO_REUSEADDR` socket option; normally it should be `true` for server sockets (sockets that you will eventually call `SocketExt::accept` on), and `false` for client sockets. (Failing to set this flag on a server socket may cause `SocketExt::bind` to return `IOErrorEnum::AddressInUse` if the server program is stopped and then immediately restarted.) If `self` is a UDP socket, then `allow_reuse` determines whether or not other UDP sockets can be bound to the same address at the same time. In particular, you can have several UDP sockets bound to the same address, and they will all receive all of the multicast and broadcast packets sent to that address. (The behavior of unicast UDP packets to an address with multiple listeners is not defined.) ## `address` a `SocketAddress` specifying the local address. ## `allow_reuse` whether to allow reusing this address # Returns `true` on success, `false` on error. Checks and resets the pending connect error for the socket. This is used to check for errors when `SocketExt::connect` is used in non-blocking mode. # Returns `true` if no error, `false` otherwise, setting `error` to the error Closes the socket, shutting down any active connection. Closing a socket does not wait for all outstanding I/O operations to finish, so the caller should not rely on them to be guaranteed to complete even if the close returns with no error. Once the socket is closed, all other operations will return `IOErrorEnum::Closed`. Closing a socket multiple times will not return an error. Sockets will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Beware that due to the way that TCP works, it is possible for recently-sent data to be lost if either you close a socket while the `glib::IOCondition::In` condition is set, or else if the remote connection tries to send something to you after you close the socket but before it has finished reading all of the data you sent. There is no easy generic way to avoid this problem; the easiest fix is to design the network protocol such that the client will never send data "out of turn". Another solution is for the server to half-close the connection by calling `SocketExt::shutdown` with only the `shutdown_write` flag set, and then wait for the client to notice this and close its side of the connection, after which the server can safely call `SocketExt::close`. (This is what `TcpConnection` does if you call `TcpConnectionExt::set_graceful_disconnect`. But of course, this only works if the client will close its connection after the server does.) # Returns `true` on success, `false` on error Checks on the readiness of `self` to perform operations. The operations specified in `condition` are checked for and masked against the currently-satisfied conditions on `self`. The result is returned. Note that on Windows, it is possible for an operation to return `IOErrorEnum::WouldBlock` even immediately after `SocketExt::condition_check` has claimed that the socket is ready for writing. Rather than calling `SocketExt::condition_check` and then writing to the socket if it succeeds, it is generally better to simply try writing to the socket right away, and try again later if the initial attempt returns `IOErrorEnum::WouldBlock`. It is meaningless to specify `glib::IOCondition::Err` or `glib::IOCondition::Hup` in condition; these conditions will always be set in the output if they are true. This call never blocks. ## `condition` a `glib::IOCondition` mask to check # Returns the `glib::IOCondition` mask of the current state Waits for up to `timeout` microseconds for `condition` to become true on `self`. If the condition is met, `true` is returned. If `cancellable` is cancelled before the condition is met, or if `timeout` (or the socket's `Socket:timeout`) is reached before the condition is met, then `false` is returned and `error`, if non-`None`, is set to the appropriate value (`IOErrorEnum::Cancelled` or `IOErrorEnum::TimedOut`). If you don't want a timeout, use `SocketExt::condition_wait`. (Alternatively, you can pass -1 for `timeout`.) Note that although `timeout` is in microseconds for consistency with other GLib APIs, this function actually only has millisecond resolution, and the behavior is undefined if `timeout` is not an exact number of milliseconds. ## `condition` a `glib::IOCondition` mask to wait for ## `timeout` the maximum time (in microseconds) to wait, or -1 ## `cancellable` a `Cancellable`, or `None` # Returns `true` if the condition was met, `false` otherwise Waits for `condition` to become true on `self`. When the condition is met, `true` is returned. If `cancellable` is cancelled before the condition is met, or if the socket has a timeout set and it is reached before the condition is met, then `false` is returned and `error`, if non-`None`, is set to the appropriate value (`IOErrorEnum::Cancelled` or `IOErrorEnum::TimedOut`). See also `SocketExt::condition_timed_wait`. ## `condition` a `glib::IOCondition` mask to wait for ## `cancellable` a `Cancellable`, or `None` # Returns `true` if the condition was met, `false` otherwise Connect the socket to the specified remote address. For connection oriented socket this generally means we attempt to make a connection to the `address`. For a connection-less socket it sets the default address for `Socket::send` and discards all incoming datagrams from other sources. Generally connection oriented sockets can only connect once, but connection-less sockets can connect multiple times to change the default address. If the connect call needs to do network I/O it will block, unless non-blocking I/O is enabled. Then `IOErrorEnum::Pending` is returned and the user can be notified of the connection finishing by waiting for the G_IO_OUT condition. The result of the connection must then be checked with `SocketExt::check_connect_result`. ## `address` a `SocketAddress` specifying the remote address. ## `cancellable` a `Cancellable` or `None` # Returns `true` if connected, `false` on error. Creates a `SocketConnection` subclass of the right type for `self`. # Returns a `SocketConnection` Creates a `glib::Source` that can be attached to a `glib::MainContext` to monitor for the availability of the specified `condition` on the socket. The `glib::Source` keeps a reference to the `self`. The callback on the source is of the `GSocketSourceFunc` type. It is meaningless to specify `glib::IOCondition::Err` or `glib::IOCondition::Hup` in `condition`; these conditions will always be reported output if they are true. `cancellable` if not `None` can be used to cancel the source, which will cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using `CancellableExt::is_cancelled`. If `self` has a timeout set, and it is reached before `condition` occurs, the source will then trigger anyway, reporting `glib::IOCondition::In` or `glib::IOCondition::Out` depending on `condition`. However, `self` will have been marked as having had a timeout, and so the next `Socket` I/O method you call will then fail with a `IOErrorEnum::TimedOut`. ## `condition` a `glib::IOCondition` mask to monitor ## `cancellable` a `Cancellable` or `None` # Returns a newly allocated `glib::Source`, free with `glib::Source::unref`. Get the amount of data pending in the OS input buffer, without blocking. If `self` is a UDP or SCTP socket, this will return the size of just the next packet, even if additional packets are buffered after that one. Note that on Windows, this function is rather inefficient in the UDP case, and so if you know any plausible upper bound on the size of the incoming packet, it is better to just do a `Socket::receive` with a buffer of that size, rather than calling `SocketExt::get_available_bytes` first and then doing a receive of exactly the right size. # Returns the number of bytes that can be read from the socket without blocking or truncating, or -1 on error. Gets the blocking mode of the socket. For details on blocking I/O, see `SocketExt::set_blocking`. # Returns `true` if blocking I/O is used, `false` otherwise. Gets the broadcast setting on `self`; if `true`, it is possible to send packets to broadcast addresses. # Returns the broadcast setting on `self` Returns the credentials of the foreign process connected to this socket, if any (e.g. it is only supported for `SocketFamily::Unix` sockets). If this operation isn't supported on the OS, the method fails with the `IOErrorEnum::NotSupported` error. On Linux this is implemented by reading the `SO_PEERCRED` option on the underlying socket. Other ways to obtain credentials from a foreign peer includes the `UnixCredentialsMessage` type and `UnixConnection::send_credentials` / `UnixConnection::receive_credentials` functions. # Returns `None` if `error` is set, otherwise a `Credentials` object that must be freed with `gobject::ObjectExt::unref`. Gets the socket family of the socket. # Returns a `SocketFamily` Returns the underlying OS socket object. On unix this is a socket file descriptor, and on Windows this is a Winsock2 SOCKET handle. This may be useful for doing platform specific or otherwise unusual operations on the socket. # Returns the file descriptor of the socket. Gets the keepalive mode of the socket. For details on this, see `SocketExt::set_keepalive`. # Returns `true` if keepalive is active, `false` otherwise. Gets the listen backlog setting of the socket. For details on this, see `SocketExt::set_listen_backlog`. # Returns the maximum number of pending connections. Try to get the local address of a bound socket. This is only useful if the socket has been bound to a local address, either explicitly or implicitly when connecting. # Returns a `SocketAddress` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Gets the multicast loopback setting on `self`; if `true` (the default), outgoing multicast packets will be looped back to multicast listeners on the same host. # Returns the multicast loopback setting on `self` Gets the multicast time-to-live setting on `self`; see `SocketExt::set_multicast_ttl` for more details. # Returns the multicast time-to-live setting on `self` Gets the value of an integer-valued option on `self`, as with `getsockopt`. (If you need to fetch a non-integer-valued option, you will need to call `getsockopt` directly.) The [][gio-gnetworking.h] header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers. Note that even for socket options that are a single byte in size, `value` is still a pointer to a `gint` variable, not a `guchar`; `SocketExt::get_option` will handle the conversion internally. ## `level` the "API level" of the option (eg, `SOL_SOCKET`) ## `optname` the "name" of the option (eg, `SO_BROADCAST`) ## `value` return location for the option value # Returns success or failure. On failure, `error` will be set, and the system error value (`errno` or WSAGetLastError()) will still be set to the result of the `getsockopt` call. Gets the socket protocol id the socket was created with. In case the protocol is unknown, -1 is returned. # Returns a protocol id, or -1 if unknown Try to get the remote address of a connected socket. This is only useful for connection oriented sockets that have been connected. # Returns a `SocketAddress` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Gets the socket type of the socket. # Returns a `SocketType` Gets the timeout setting of the socket. For details on this, see `SocketExt::set_timeout`. # Returns the timeout in seconds Gets the unicast time-to-live setting on `self`; see `SocketExt::set_ttl` for more details. # Returns the time-to-live setting on `self` Checks whether a socket is closed. # Returns `true` if socket is closed, `false` otherwise Check whether the socket is connected. This is only useful for connection-oriented sockets. If using `SocketExt::shutdown`, this function will return `true` until the socket has been shut down for reading and writing. If you do a non-blocking connect, this function will not return `true` until after you call `SocketExt::check_connect_result`. # Returns `true` if socket is connected, `false` otherwise. Registers `self` to receive multicast messages sent to `group`. `self` must be a `SocketType::Datagram` socket, and must have been bound to an appropriate interface and port with `SocketExt::bind`. If `iface` is `None`, the system will automatically pick an interface to bind to based on `group`. If `source_specific` is `true`, source-specific multicast as defined in RFC 4604 is used. Note that on older platforms this may fail with a `IOErrorEnum::NotSupported` error. To bind to a given source-specific multicast address, use `SocketExt::join_multicast_group_ssm` instead. ## `group` a `InetAddress` specifying the group address to join. ## `source_specific` `true` if source-specific multicast should be used ## `iface` Name of the interface to use, or `None` # Returns `true` on success, `false` on error. Registers `self` to receive multicast messages sent to `group`. `self` must be a `SocketType::Datagram` socket, and must have been bound to an appropriate interface and port with `SocketExt::bind`. If `iface` is `None`, the system will automatically pick an interface to bind to based on `group`. If `source_specific` is not `None`, use source-specific multicast as defined in RFC 4604. Note that on older platforms this may fail with a `IOErrorEnum::NotSupported` error. Note that this function can be called multiple times for the same `group` with different `source_specific` in order to receive multicast packets from more than one source. Feature: `v2_56` ## `group` a `InetAddress` specifying the group address to join. ## `source_specific` a `InetAddress` specifying the source-specific multicast address or `None` to ignore. ## `iface` Name of the interface to use, or `None` # Returns `true` on success, `false` on error. Removes `self` from the multicast group defined by `group`, `iface`, and `source_specific` (which must all have the same values they had when you joined the group). `self` remains bound to its address and port, and can still receive unicast messages after calling this. To unbind to a given source-specific multicast address, use `SocketExt::leave_multicast_group_ssm` instead. ## `group` a `InetAddress` specifying the group address to leave. ## `source_specific` `true` if source-specific multicast was used ## `iface` Interface used # Returns `true` on success, `false` on error. Removes `self` from the multicast group defined by `group`, `iface`, and `source_specific` (which must all have the same values they had when you joined the group). `self` remains bound to its address and port, and can still receive unicast messages after calling this. Feature: `v2_56` ## `group` a `InetAddress` specifying the group address to leave. ## `source_specific` a `InetAddress` specifying the source-specific multicast address or `None` to ignore. ## `iface` Name of the interface to use, or `None` # Returns `true` on success, `false` on error. Marks the socket as a server socket, i.e. a socket that is used to accept incoming requests using `SocketExt::accept`. Before calling this the socket must be bound to a local address using `SocketExt::bind`. To set the maximum amount of outstanding clients, use `SocketExt::set_listen_backlog`. # Returns `true` on success, `false` on error. Receive data (up to `size` bytes) from a socket. This is mainly used by connection-oriented sockets; it is identical to `Socket::receive_from` with `address` set to `None`. For `SocketType::Datagram` and `SocketType::Seqpacket` sockets, `Socket::receive` will always read either 0 or 1 complete messages from the socket. If the received message is too large to fit in `buffer`, then the data beyond `size` bytes will be discarded, without any explicit indication that this has occurred. For `SocketType::Stream` sockets, `Socket::receive` can return any number of bytes, up to `size`. If more than `size` bytes have been received, the additional data will be returned in future calls to `Socket::receive`. If the socket is in blocking mode the call will block until there is some data to receive, the connection is closed, or there is an error. If there is no data available and the socket is in non-blocking mode, a `IOErrorEnum::WouldBlock` error will be returned. To be notified when data is available, wait for the `glib::IOCondition::In` condition. On error -1 is returned and `error` is set accordingly. ## `buffer` a buffer to read data into (which should be at least `size` bytes long). ## `size` the number of bytes you want to read from the socket ## `cancellable` a `Cancellable` or `None` # Returns Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error Receive data (up to `size` bytes) from a socket. If `address` is non-`None` then `address` will be set equal to the source address of the received packet. `address` is owned by the caller. See `Socket::receive` for additional information. ## `address` a pointer to a `SocketAddress` pointer, or `None` ## `buffer` a buffer to read data into (which should be at least `size` bytes long). ## `size` the number of bytes you want to read from the socket ## `cancellable` a `Cancellable` or `None` # Returns Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error Receive data from a socket. For receiving multiple messages, see `Socket::receive_messages`; for easier use, see `Socket::receive` and `Socket::receive_from`. If `address` is non-`None` then `address` will be set equal to the source address of the received packet. `address` is owned by the caller. `vector` must point to an array of `InputVector` structs and `num_vectors` must be the length of this array. These structs describe the buffers that received data will be scattered into. If `num_vectors` is -1, then `vectors` is assumed to be terminated by a `InputVector` with a `None` buffer pointer. As a special case, if `num_vectors` is 0 (in which case, `vectors` may of course be `None`), then a single byte is received and discarded. This is to facilitate the common practice of sending a single '\0' byte for the purposes of transferring ancillary data. `messages`, if non-`None`, will be set to point to a newly-allocated array of `SocketControlMessage` instances or `None` if no such messages was received. These correspond to the control messages received from the kernel, one `SocketControlMessage` per message from the kernel. This array is `None`-terminated and must be freed by the caller using `g_free` after calling `gobject::ObjectExt::unref` on each element. If `messages` is `None`, any control messages received will be discarded. `num_messages`, if non-`None`, will be set to the number of control messages received. If both `messages` and `num_messages` are non-`None`, then `num_messages` gives the number of `SocketControlMessage` instances in `messages` (ie: not including the `None` terminator). `flags` is an in/out parameter. The commonly available arguments for this are available in the `SocketMsgFlags` enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too (and `Socket::receive_message` may pass system-specific flags out). Flags passed in to the parameter affect the receive operation; flags returned out of it are relevant to the specific returned message. As with `Socket::receive`, data may be discarded if `self` is `SocketType::Datagram` or `SocketType::Seqpacket` and you do not provide enough buffer space to read a complete message. You can pass `SocketMsgFlags::Peek` in `flags` to peek at the current message without removing it from the receive queue, but there is no portable way to find out the length of the message other than by reading it into a sufficiently-large buffer. If the socket is in blocking mode the call will block until there is some data to receive, the connection is closed, or there is an error. If there is no data available and the socket is in non-blocking mode, a `IOErrorEnum::WouldBlock` error will be returned. To be notified when data is available, wait for the `glib::IOCondition::In` condition. On error -1 is returned and `error` is set accordingly. ## `address` a pointer to a `SocketAddress` pointer, or `None` ## `vectors` an array of `InputVector` structs ## `num_vectors` the number of elements in `vectors`, or -1 ## `messages` a pointer which may be filled with an array of `GSocketControlMessages`, or `None` ## `num_messages` a pointer which will be filled with the number of elements in `messages`, or `None` ## `flags` a pointer to an int containing `SocketMsgFlags` flags ## `cancellable` a `Cancellable` or `None` # Returns Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error Receive multiple data messages from `self` in one go. This is the most complicated and fully-featured version of this call. For easier use, see `Socket::receive`, `Socket::receive_from`, and `Socket::receive_message`. `messages` must point to an array of `InputMessage` structs and `num_messages` must be the length of this array. Each `InputMessage` contains a pointer to an array of `InputVector` structs describing the buffers that the data received in each message will be written to. Using multiple `GInputVectors` is more memory-efficient than manually copying data out of a single buffer to multiple sources, and more system-call-efficient than making multiple calls to `Socket::receive`, such as in scenarios where a lot of data packets need to be received (e.g. high-bandwidth video streaming over RTP/UDP). `flags` modify how all messages are received. The commonly available arguments for this are available in the `SocketMsgFlags` enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. These flags affect the overall receive operation. Flags affecting individual messages are returned in `InputMessage.flags`. The other members of `InputMessage` are treated as described in its documentation. If `Socket:blocking` is `true` the call will block until `num_messages` have been received, or the end of the stream is reached. If `Socket:blocking` is `false` the call will return up to `num_messages` without blocking, or `IOErrorEnum::WouldBlock` if no messages are queued in the operating system to be received. In blocking mode, if `Socket:timeout` is positive and is reached before any messages are received, `IOErrorEnum::TimedOut` is returned, otherwise up to `num_messages` are returned. (Note: This is effectively the behaviour of `MSG_WAITFORONE` with `recvmmsg`.) To be notified when messages are available, wait for the `glib::IOCondition::In` condition. Note though that you may still receive `IOErrorEnum::WouldBlock` from `Socket::receive_messages` even if you were previously notified of a `glib::IOCondition::In` condition. If the remote peer closes the connection, any messages queued in the operating system will be returned, and subsequent calls to `Socket::receive_messages` will return 0 (with no error set). On error -1 is returned and `error` is set accordingly. An error will only be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. Feature: `v2_48` ## `messages` an array of `InputMessage` structs ## `num_messages` the number of elements in `messages` ## `flags` an int containing `SocketMsgFlags` flags for the overall operation ## `cancellable` a `Cancellable` or `None` # Returns number of messages received, or -1 on error. Note that the number of messages received may be smaller than `num_messages` if in non-blocking mode, if the peer closed the connection, or if `num_messages` was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try to receive the remaining messages. This behaves exactly the same as `Socket::receive`, except that the choice of blocking or non-blocking behavior is determined by the `blocking` argument rather than by `self`'s properties. ## `buffer` a buffer to read data into (which should be at least `size` bytes long). ## `size` the number of bytes you want to read from the socket ## `blocking` whether to do blocking or non-blocking I/O ## `cancellable` a `Cancellable` or `None` # Returns Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error Tries to send `size` bytes from `buffer` on the socket. This is mainly used by connection-oriented sockets; it is identical to `Socket::send_to` with `address` set to `None`. If the socket is in blocking mode the call will block until there is space for the data in the socket queue. If there is no space available and the socket is in non-blocking mode a `IOErrorEnum::WouldBlock` error will be returned. To be notified when space is available, wait for the `glib::IOCondition::Out` condition. Note though that you may still receive `IOErrorEnum::WouldBlock` from `Socket::send` even if you were previously notified of a `glib::IOCondition::Out` condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) On error -1 is returned and `error` is set accordingly. ## `buffer` the buffer containing the data to send. ## `size` the number of bytes to send ## `cancellable` a `Cancellable` or `None` # Returns Number of bytes written (which may be less than `size`), or -1 on error Send data to `address` on `self`. For sending multiple messages see `Socket::send_messages`; for easier use, see `Socket::send` and `Socket::send_to`. If `address` is `None` then the message is sent to the default receiver (set by `SocketExt::connect`). `vectors` must point to an array of `OutputVector` structs and `num_vectors` must be the length of this array. (If `num_vectors` is -1, then `vectors` is assumed to be terminated by a `OutputVector` with a `None` buffer pointer.) The `OutputVector` structs describe the buffers that the sent data will be gathered from. Using multiple `GOutputVectors` is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to `Socket::send`. `messages`, if non-`None`, is taken to point to an array of `num_messages` `SocketControlMessage` instances. These correspond to the control messages to be sent on the socket. If `num_messages` is -1 then `messages` is treated as a `None`-terminated array. `flags` modify how the message is sent. The commonly available arguments for this are available in the `SocketMsgFlags` enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. If the socket is in blocking mode the call will block until there is space for the data in the socket queue. If there is no space available and the socket is in non-blocking mode a `IOErrorEnum::WouldBlock` error will be returned. To be notified when space is available, wait for the `glib::IOCondition::Out` condition. Note though that you may still receive `IOErrorEnum::WouldBlock` from `Socket::send` even if you were previously notified of a `glib::IOCondition::Out` condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) On error -1 is returned and `error` is set accordingly. ## `address` a `SocketAddress`, or `None` ## `vectors` an array of `OutputVector` structs ## `num_vectors` the number of elements in `vectors`, or -1 ## `messages` a pointer to an array of `GSocketControlMessages`, or `None`. ## `num_messages` number of elements in `messages`, or -1. ## `flags` an int containing `SocketMsgFlags` flags ## `cancellable` a `Cancellable` or `None` # Returns Number of bytes written (which may be less than `size`), or -1 on error Send multiple data messages from `self` in one go. This is the most complicated and fully-featured version of this call. For easier use, see `Socket::send`, `Socket::send_to`, and `Socket::send_message`. `messages` must point to an array of `OutputMessage` structs and `num_messages` must be the length of this array. Each `OutputMessage` contains an address to send the data to, and a pointer to an array of `OutputVector` structs to describe the buffers that the data to be sent for each message will be gathered from. Using multiple `GOutputVectors` is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to `Socket::send`. Sending multiple messages in one go avoids the overhead of making a lot of syscalls in scenarios where a lot of data packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), or where the same data needs to be sent to multiple recipients. `flags` modify how the message is sent. The commonly available arguments for this are available in the `SocketMsgFlags` enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. If the socket is in blocking mode the call will block until there is space for all the data in the socket queue. If there is no space available and the socket is in non-blocking mode a `IOErrorEnum::WouldBlock` error will be returned if no data was written at all, otherwise the number of messages sent will be returned. To be notified when space is available, wait for the `glib::IOCondition::Out` condition. Note though that you may still receive `IOErrorEnum::WouldBlock` from `Socket::send` even if you were previously notified of a `glib::IOCondition::Out` condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) On error -1 is returned and `error` is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. Feature: `v2_44` ## `messages` an array of `OutputMessage` structs ## `num_messages` the number of elements in `messages` ## `flags` an int containing `SocketMsgFlags` flags ## `cancellable` a `Cancellable` or `None` # Returns number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than `num_messages` if the socket is non-blocking or if `num_messages` was larger than UIO_MAXIOV (1024), in which case the caller may re-try to send the remaining messages. Tries to send `size` bytes from `buffer` to `address`. If `address` is `None` then the message is sent to the default receiver (set by `SocketExt::connect`). See `Socket::send` for additional information. ## `address` a `SocketAddress`, or `None` ## `buffer` the buffer containing the data to send. ## `size` the number of bytes to send ## `cancellable` a `Cancellable` or `None` # Returns Number of bytes written (which may be less than `size`), or -1 on error This behaves exactly the same as `Socket::send`, except that the choice of blocking or non-blocking behavior is determined by the `blocking` argument rather than by `self`'s properties. ## `buffer` the buffer containing the data to send. ## `size` the number of bytes to send ## `blocking` whether to do blocking or non-blocking I/O ## `cancellable` a `Cancellable` or `None` # Returns Number of bytes written (which may be less than `size`), or -1 on error Sets the blocking mode of the socket. In blocking mode all operations (which don’t take an explicit blocking parameter) block until they succeed or there is an error. In non-blocking mode all functions return results immediately or with a `IOErrorEnum::WouldBlock` error. All sockets are created in blocking mode. However, note that the platform level socket is always non-blocking, and blocking mode is a GSocket level feature. ## `blocking` Whether to use blocking I/O or not. Sets whether `self` should allow sending to broadcast addresses. This is `false` by default. ## `broadcast` whether `self` should allow sending to broadcast addresses Sets or unsets the `SO_KEEPALIVE` flag on the underlying socket. When this flag is set on a socket, the system will attempt to verify that the remote socket endpoint is still present if a sufficiently long period of time passes with no data being exchanged. If the system is unable to verify the presence of the remote endpoint, it will automatically close the connection. This option is only functional on certain kinds of sockets. (Notably, `SocketProtocol::Tcp` sockets.) The exact time between pings is system- and protocol-dependent, but will normally be at least two hours. Most commonly, you would set this flag on a server socket if you want to allow clients to remain idle for long periods of time, but also want to ensure that connections are eventually garbage-collected if clients crash or become unreachable. ## `keepalive` Value for the keepalive flag Sets the maximum number of outstanding connections allowed when listening on this socket. If more clients than this are connecting to the socket and the application is not handling them on time then the new connections will be refused. Note that this must be called before `SocketExt::listen` and has no effect if called after that. ## `backlog` the maximum number of pending connections. Sets whether outgoing multicast packets will be received by sockets listening on that multicast address on the same host. This is `true` by default. ## `loopback` whether `self` should receive messages sent to its multicast groups from the local host Sets the time-to-live for outgoing multicast datagrams on `self`. By default, this is 1, meaning that multicast packets will not leave the local network. ## `ttl` the time-to-live value for all multicast datagrams on `self` Sets the value of an integer-valued option on `self`, as with `setsockopt`. (If you need to set a non-integer-valued option, you will need to call `setsockopt` directly.) The [][gio-gnetworking.h] header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers. ## `level` the "API level" of the option (eg, `SOL_SOCKET`) ## `optname` the "name" of the option (eg, `SO_BROADCAST`) ## `value` the value to set the option to # Returns success or failure. On failure, `error` will be set, and the system error value (`errno` or WSAGetLastError()) will still be set to the result of the `setsockopt` call. Sets the time in seconds after which I/O operations on `self` will time out if they have not yet completed. On a blocking socket, this means that any blocking `Socket` operation will time out after `timeout` seconds of inactivity, returning `IOErrorEnum::TimedOut`. On a non-blocking socket, calls to `SocketExt::condition_wait` will also fail with `IOErrorEnum::TimedOut` after the given time. Sources created with `Socket::create_source` will trigger after `timeout` seconds of inactivity, with the requested condition set, at which point calling `Socket::receive`, `Socket::send`, `SocketExt::check_connect_result`, etc, will fail with `IOErrorEnum::TimedOut`. If `timeout` is 0 (the default), operations will never time out on their own. Note that if an I/O operation is interrupted by a signal, this may cause the timeout to be reset. ## `timeout` the timeout for `self`, in seconds, or 0 for none Sets the time-to-live for outgoing unicast packets on `self`. By default the platform-specific default value is used. ## `ttl` the time-to-live value for all unicast packets on `self` Shut down part or all of a full-duplex connection. If `shutdown_read` is `true` then the receiving side of the connection is shut down, and further reading is disallowed. If `shutdown_write` is `true` then the sending side of the connection is shut down, and further writing is disallowed. It is allowed for both `shutdown_read` and `shutdown_write` to be `true`. One example where it is useful to shut down only one side of a connection is graceful disconnect for TCP connections where you close the sending side, then wait for the other side to close the connection, thus ensuring that the other side saw all sent data. ## `shutdown_read` whether to shut down the read side ## `shutdown_write` whether to shut down the write side # Returns `true` on success, `false` on error Checks if a socket is capable of speaking IPv4. IPv4 sockets are capable of speaking IPv4. On some operating systems and under some combinations of circumstances IPv6 sockets are also capable of speaking IPv4. See RFC 3493 section 3.7 for more information. No other types of sockets are currently considered as being capable of speaking IPv4. # Returns `true` if this socket can be used with IPv4. Whether the socket should allow sending to broadcast addresses. Whether the socket should allow sending to broadcast addresses. Whether outgoing multicast packets loop back to the local host. Whether outgoing multicast packets loop back to the local host. Time-to-live out outgoing multicast packets Time-to-live out outgoing multicast packets The timeout in seconds on socket I/O The timeout in seconds on socket I/O Time-to-live for outgoing unicast packets Time-to-live for outgoing unicast packets `SocketAddress` is the equivalent of struct sockaddr in the BSD sockets API. This is an abstract class; use `InetSocketAddress` for internet sockets, or `UnixSocketAddress` for UNIX domain sockets. # Implements [`SocketAddressExt`](trait.SocketAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `SocketAddress` methods. # Implementors [`InetSocketAddress`](struct.InetSocketAddress.html), [`SocketAddress`](struct.SocketAddress.html), [`UnixSocketAddress`](struct.UnixSocketAddress.html) Creates a `SocketAddress` subclass corresponding to the native struct sockaddr `native`. ## `native` a pointer to a struct sockaddr ## `len` the size of the memory location pointed to by `native` # Returns a new `SocketAddress` if `native` could successfully be converted, otherwise `None` Gets the socket family type of `self`. # Returns the socket family type of `self` Gets the size of `self`'s native struct sockaddr. You can use this to allocate memory to pass to `SocketAddressExt::to_native`. # Returns the size of the native struct sockaddr that `self` represents Converts a `SocketAddress` to a native struct sockaddr, which can be passed to low-level functions like `connect` or `bind`. If not enough space is available, a `IOErrorEnum::NoSpace` error is returned. If the address type is not known on the system then a `IOErrorEnum::NotSupported` error is returned. ## `dest` a pointer to a memory location that will contain the native struct sockaddr ## `destlen` the size of `dest`. Must be at least as large as `SocketAddressExt::get_native_size` # Returns `true` if `dest` was filled in, `false` on error Enumerator type for objects that contain or generate `SocketAddress` instances. # Implements [`SocketAddressEnumeratorExt`](trait.SocketAddressEnumeratorExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `SocketAddressEnumerator` methods. # Implementors [`SocketAddressEnumerator`](struct.SocketAddressEnumerator.html) Retrieves the next `SocketAddress` from `self`. Note that this may block for some amount of time. (Eg, a `NetworkAddress` may need to do a DNS lookup before it can return an address.) Use `SocketAddressEnumeratorExt::next_async` if you need to avoid blocking. If `self` is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), then the first call to `SocketAddressEnumeratorExt::next` will return an appropriate error in *`error`. However, if the first call to `SocketAddressEnumeratorExt::next` succeeds, then any further internal errors (other than `cancellable` being triggered) will be ignored. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `SocketAddress` (owned by the caller), or `None` on error (in which case *`error` will be set) or if there are no more addresses. Asynchronously retrieves the next `SocketAddress` from `self` and then calls `callback`, which must call `SocketAddressEnumeratorExt::next_finish` to get the result. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Retrieves the result of a completed call to `SocketAddressEnumeratorExt::next_async`. See `SocketAddressEnumeratorExt::next` for more information about error handling. ## `result` a `AsyncResult` # Returns a `SocketAddress` (owned by the caller), or `None` on error (in which case *`error` will be set) or if there are no more addresses. `SocketClient` is a lightweight high-level utility class for connecting to a network host using a connection oriented socket type. You create a `SocketClient` object, set any options you want, and then call a sync or async connect operation, which returns a `SocketConnection` subclass on success. The type of the `SocketConnection` object returned depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a `TcpConnection`. As `SocketClient` is a lightweight object, you don't need to cache it. You can just create a new one any time you need one. # Implements [`SocketClientExt`](trait.SocketClientExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `SocketClient` methods. # Implementors [`SocketClient`](struct.SocketClient.html) Creates a new `SocketClient` with the default options. # Returns a `SocketClient`. Free the returned object with `gobject::ObjectExt::unref`. Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the `ProxyResolver`, `SocketClient` will consider this protocol as supported but will not try to find a `Proxy` instance to handle handshaking. The application must check for this case by calling `SocketConnectionExt::get_remote_address` on the returned `SocketConnection`, and seeing if it's a `ProxyAddress` of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself. This should be used for proxy protocols that are dialects of another protocol such as HTTP proxy. It also allows cohabitation of proxy protocols that are reused between protocols. A good example is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also be use as generic socket proxy through the HTTP CONNECT method. When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake. ## `protocol` The proxy protocol Tries to resolve the `connectable` and make a network connection to it. Upon a successful connection, a new `SocketConnection` is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. The type of the `SocketConnection` object returned depends on the type of the underlying socket that is used. For instance, for a TCP/IP connection it will be a `TcpConnection`. The socket created will be the same family as the address that the `connectable` resolves to, unless family is set with `SocketClientExt::set_family` or indirectly via `SocketClientExt::set_local_address`. The socket type defaults to `SocketType::Stream` but can be set with `SocketClientExt::set_socket_type`. If a local address is specified with `SocketClientExt::set_local_address` the socket will be bound to this address before connecting. ## `connectable` a `SocketConnectable` specifying the remote address. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `SocketConnection` on success, `None` on error. This is the asynchronous version of `SocketClientExt::connect`. When the operation is finished `callback` will be called. You can then call `SocketClientExt::connect_finish` to get the result of the operation. ## `connectable` a `SocketConnectable` specifying the remote address. ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` ## `user_data` user data for the callback Finishes an async connect operation. See `SocketClientExt::connect_async` ## `result` a `AsyncResult`. # Returns a `SocketConnection` on success, `None` on error. This is a helper function for `SocketClientExt::connect`. Attempts to create a TCP connection to the named host. `host_and_port` may be in any of a number of recognized formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed). If no port override is given in `host_and_port` then `default_port` will be used as the port number to connect to. In general, `host_and_port` is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and `default_port` is expected to be provided by the application. In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds. Upon a successful connection, a new `SocketConnection` is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) `None` is returned and `error` (if non-`None`) is set accordingly. ## `host_and_port` the name and optionally port of the host to connect to ## `default_port` the default port to connect to ## `cancellable` a `Cancellable`, or `None` # Returns a `SocketConnection` on success, `None` on error. This is the asynchronous version of `SocketClientExt::connect_to_host`. When the operation is finished `callback` will be called. You can then call `SocketClientExt::connect_to_host_finish` to get the result of the operation. ## `host_and_port` the name and optionally the port of the host to connect to ## `default_port` the default port to connect to ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` ## `user_data` user data for the callback Finishes an async connect operation. See `SocketClientExt::connect_to_host_async` ## `result` a `AsyncResult`. # Returns a `SocketConnection` on success, `None` on error. Attempts to create a TCP connection to a service. This call looks up the SRV record for `service` at `domain` for the "tcp" protocol. It then attempts to connect, in turn, to each of the hosts providing the service until either a connection succeeds or there are no hosts remaining. Upon a successful connection, a new `SocketConnection` is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) `None` is returned and `error` (if non-`None`) is set accordingly. ## `domain` a domain name ## `service` the name of the service to connect to ## `cancellable` a `Cancellable`, or `None` # Returns a `SocketConnection` if successful, or `None` on error This is the asynchronous version of `SocketClientExt::connect_to_service`. ## `domain` a domain name ## `service` the name of the service to connect to ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` ## `user_data` user data for the callback Finishes an async connect operation. See `SocketClientExt::connect_to_service_async` ## `result` a `AsyncResult`. # Returns a `SocketConnection` on success, `None` on error. This is a helper function for `SocketClientExt::connect`. Attempts to create a TCP connection with a network URI. `uri` may be any valid URI containing an "authority" (hostname/port) component. If a port is not specified in the URI, `default_port` will be used. TLS will be negotiated if `SocketClient:tls` is `true`. (`SocketClient` does not know to automatically assume TLS for certain URI schemes.) Using this rather than `SocketClientExt::connect` or `SocketClientExt::connect_to_host` allows `SocketClient` to determine when to use application-specific proxy protocols. Upon a successful connection, a new `SocketConnection` is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) `None` is returned and `error` (if non-`None`) is set accordingly. ## `uri` A network URI ## `default_port` the default port to connect to ## `cancellable` a `Cancellable`, or `None` # Returns a `SocketConnection` on success, `None` on error. This is the asynchronous version of `SocketClientExt::connect_to_uri`. When the operation is finished `callback` will be called. You can then call `SocketClientExt::connect_to_uri_finish` to get the result of the operation. ## `uri` a network uri ## `default_port` the default port to connect to ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` ## `user_data` user data for the callback Finishes an async connect operation. See `SocketClientExt::connect_to_uri_async` ## `result` a `AsyncResult`. # Returns a `SocketConnection` on success, `None` on error. Gets the proxy enable state; see `SocketClientExt::set_enable_proxy` # Returns whether proxying is enabled Gets the socket family of the socket client. See `SocketClientExt::set_family` for details. # Returns a `SocketFamily` Gets the local address of the socket client. See `SocketClientExt::set_local_address` for details. # Returns a `SocketAddress` or `None`. Do not free. Gets the protocol name type of the socket client. See `SocketClientExt::set_protocol` for details. # Returns a `SocketProtocol` Gets the `ProxyResolver` being used by `self`. Normally, this will be the resolver returned by `ProxyResolver::get_default`, but you can override it with `SocketClientExt::set_proxy_resolver`. # Returns The `ProxyResolver` being used by `self`. Gets the socket type of the socket client. See `SocketClientExt::set_socket_type` for details. # Returns a `SocketFamily` Gets the I/O timeout time for sockets created by `self`. See `SocketClientExt::set_timeout` for details. # Returns the timeout in seconds Gets whether `self` creates TLS connections. See `SocketClientExt::set_tls` for details. # Returns whether `self` uses TLS Gets the TLS validation flags used creating TLS connections via `self`. # Returns the TLS validation flags Sets whether or not `self` attempts to make connections via a proxy server. When enabled (the default), `SocketClient` will use a `ProxyResolver` to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation. See also `SocketClientExt::set_proxy_resolver`. ## `enable` whether to enable proxies Sets the socket family of the socket client. If this is set to something other than `SocketFamily::Invalid` then the sockets created by this object will be of the specified family. This might be useful for instance if you want to force the local connection to be an ipv4 socket, even though the address might be an ipv6 mapped to ipv4 address. ## `family` a `SocketFamily` Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not `None`) before connecting. This is useful if you want to ensure that the local side of the connection is on a specific port, or on a specific interface. ## `address` a `SocketAddress`, or `None` Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol. If `protocol` is `0` that means to use the default protocol for the socket family and type. ## `protocol` a `SocketProtocol` Overrides the `ProxyResolver` used by `self`. You can call this if you want to use specific proxies, rather than using the system default proxy settings. Note that whether or not the proxy resolver is actually used depends on the setting of `SocketClient:enable-proxy`, which is not changed by this function (but which is `true` by default) ## `proxy_resolver` a `ProxyResolver`, or `None` for the default. Sets the socket type of the socket client. The sockets created by this object will be of the specified type. It doesn't make sense to specify a type of `SocketType::Datagram`, as GSocketClient is used for connection oriented services. ## `type_` a `SocketType` Sets the I/O timeout for sockets created by `self`. `timeout` is a time in seconds, or 0 for no timeout (the default). The timeout value affects the initial connection attempt as well, so setting this may cause calls to `SocketClientExt::connect`, etc, to fail with `IOErrorEnum::TimedOut`. ## `timeout` the timeout Sets whether `self` creates TLS (aka SSL) connections. If `tls` is `true`, `self` will wrap its connections in a `TlsClientConnection` and perform a TLS handshake when connecting. Note that since `SocketClient` must return a `SocketConnection`, but `TlsClientConnection` is not a `SocketConnection`, this actually wraps the resulting `TlsClientConnection` in a `TcpWrapperConnection` when returning it. You can use `TcpWrapperConnection::get_base_io_stream` on the return value to extract the `TlsClientConnection`. If you need to modify the behavior of the TLS handshake (eg, by setting a client-side certificate to use, or connecting to the `TlsConnection::accept-certificate` signal), you can connect to `self`'s `SocketClient::event` signal and wait for it to be emitted with `SocketClientEvent::TlsHandshaking`, which will give you a chance to see the `TlsClientConnection` before the handshake starts. ## `tls` whether to use TLS Sets the TLS validation flags used when creating TLS connections via `self`. The default value is `TlsCertificateFlags::ValidateAll`. ## `flags` the validation flags Emitted when `client`'s activity on `connectable` changes state. Among other things, this can be used to provide progress information about a network connection in the UI. The meanings of the different `event` values are as follows: - `SocketClientEvent::Resolving`: `client` is about to look up `connectable` in DNS. `connection` will be `None`. - `SocketClientEvent::Resolved`: `client` has successfully resolved `connectable` in DNS. `connection` will be `None`. - `SocketClientEvent::Connecting`: `client` is about to make a connection to a remote host; either a proxy server or the destination server itself. `connection` is the `SocketConnection`, which is not yet connected. Since GLib 2.40, you can access the remote address via `SocketConnectionExt::get_remote_address`. - `SocketClientEvent::Connected`: `client` has successfully connected to a remote host. `connection` is the connected `SocketConnection`. - `SocketClientEvent::ProxyNegotiating`: `client` is about to negotiate with a proxy to get it to connect to `connectable`. `connection` is the `SocketConnection` to the proxy server. - `SocketClientEvent::ProxyNegotiated`: `client` has negotiated a connection to `connectable` through a proxy server. `connection` is the stream returned from `Proxy::connect`, which may or may not be a `SocketConnection`. - `SocketClientEvent::TlsHandshaking`: `client` is about to begin a TLS handshake. `connection` is a `TlsClientConnection`. - `SocketClientEvent::TlsHandshaked`: `client` has successfully completed the TLS handshake. `connection` is a `TlsClientConnection`. - `SocketClientEvent::Complete`: `client` has either successfully connected to `connectable` (in which case `connection` is the `SocketConnection` that it will be returning to the caller) or has failed (in which case `connection` is `None` and the client is about to return an error). Each event except `SocketClientEvent::Complete` may be emitted multiple times (or not at all) for a given connectable (in particular, if `client` ends up attempting to connect to more than one address). However, if `client` emits the `SocketClient::event` signal at all for a given connectable, that it will always emit it with `SocketClientEvent::Complete` when it is done. Note that there may be additional `SocketClientEvent` values in the future; unrecognized `event` values should be ignored. ## `event` the event that is occurring ## `connectable` the `SocketConnectable` that `event` is occurring on ## `connection` the current representation of the connection The proxy resolver to use The proxy resolver to use Describes an event occurring on a `SocketClient`. See the `SocketClient::event` signal for more details. Additional values may be added to this type in the future. The client is doing a DNS lookup. The client has completed a DNS lookup. The client is connecting to a remote host (either a proxy or the destination server). The client has connected to a remote host. The client is negotiating with a proxy to connect to the destination server. The client has negotiated with the proxy server. The client is performing a TLS handshake. The client has performed a TLS handshake. The client is done with a particular `SocketConnectable`. Objects that describe one or more potential socket endpoints implement `SocketConnectable`. Callers can then use `SocketConnectable::enumerate` to get a `SocketAddressEnumerator` to try out each socket address in turn until one succeeds, as shown in the sample code below. ```C MyConnectionType * connect_to_host (const char *hostname, guint16 port, GCancellable *cancellable, GError **error) { MyConnection *conn = NULL; GSocketConnectable *addr; GSocketAddressEnumerator *enumerator; GSocketAddress *sockaddr; GError *conn_error = NULL; addr = g_network_address_new (hostname, port); enumerator = g_socket_connectable_enumerate (addr); g_object_unref (addr); // Try each sockaddr until we succeed. Record the first connection error, // but not any further ones (since they'll probably be basically the same // as the first). while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) { conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error); g_object_unref (sockaddr); } g_object_unref (enumerator); if (conn) { if (conn_error) { // We couldn't connect to the first address, but we succeeded // in connecting to a later address. g_error_free (conn_error); } return conn; } else if (error) { /// Either initial lookup failed, or else the caller cancelled us. if (conn_error) g_error_free (conn_error); return NULL; } else { g_error_propagate (error, conn_error); return NULL; } } ``` # Implements [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `SocketConnectable` methods. # Implementors [`InetSocketAddress`](struct.InetSocketAddress.html), [`NetworkAddress`](struct.NetworkAddress.html), [`NetworkService`](struct.NetworkService.html), [`ProxyAddress`](struct.ProxyAddress.html), [`SocketAddress`](struct.SocketAddress.html), [`SocketConnectable`](struct.SocketConnectable.html), [`UnixSocketAddress`](struct.UnixSocketAddress.html) Creates a `SocketAddressEnumerator` for `self`. # Returns a new `SocketAddressEnumerator`. Creates a `SocketAddressEnumerator` for `self` that will return `GProxyAddresses` for addresses that you must connect to via a proxy. If `self` does not implement `SocketConnectable::proxy_enumerate`, this will fall back to calling `SocketConnectable::enumerate`. # Returns a new `SocketAddressEnumerator`. Format a `SocketConnectable` as a string. This is a human-readable format for use in debugging output, and is not a stable serialization format. It is not suitable for use in user interfaces as it exposes too much information for a user. If the `SocketConnectable` implementation does not support string formatting, the implementation’s type name will be returned as a fallback. Feature: `v2_48` # Returns the formatted string `SocketConnection` is a `IOStream` for a connected socket. They can be created either by `SocketClient` when connecting to a host, or by `SocketListener` when accepting a new client. The type of the `SocketConnection` object returned from these calls depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a `TcpConnection`. Choosing what type of object to construct is done with the socket connection factory, and it is possible for 3rd parties to register custom socket connection types for specific combination of socket family/type/protocol using `SocketConnection::factory_register_type`. To close a `SocketConnection`, use `IOStreamExt::close`. Closing both substreams of the `IOStream` separately will not close the underlying `Socket`. # Implements [`SocketConnectionExt`](trait.SocketConnectionExt.html), [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `SocketConnection` methods. # Implementors [`SocketConnection`](struct.SocketConnection.html), [`TcpConnection`](struct.TcpConnection.html) Looks up the `glib::Type` to be used when creating socket connections on sockets with the specified `family`, `type_` and `protocol_id`. If no type is registered, the `SocketConnection` base type is returned. ## `family` a `SocketFamily` ## `type_` a `SocketType` ## `protocol_id` a protocol id # Returns a `glib::Type` Looks up the `glib::Type` to be used when creating socket connections on sockets with the specified `family`, `type_` and `protocol`. If no type is registered, the `SocketConnection` base type is returned. ## `g_type` a `glib::Type`, inheriting from `G_TYPE_SOCKET_CONNECTION` ## `family` a `SocketFamily` ## `type_` a `SocketType` ## `protocol` a protocol id Connect `self` to the specified remote address. ## `address` a `SocketAddress` specifying the remote address. ## `cancellable` a `Cancellable` or `None` # Returns `true` if the connection succeeded, `false` on error Asynchronously connect `self` to the specified remote address. This clears the `Socket:blocking` flag on `self`'s underlying socket if it is currently set. Use `SocketConnectionExt::connect_finish` to retrieve the result. ## `address` a `SocketAddress` specifying the remote address. ## `cancellable` a `Cancellable` or `None` ## `callback` a `GAsyncReadyCallback` ## `user_data` user data for the callback Gets the result of a `SocketConnectionExt::connect_async` call. ## `result` the `AsyncResult` # Returns `true` if the connection succeeded, `false` on error Try to get the local address of a socket connection. # Returns a `SocketAddress` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Try to get the remote address of a socket connection. Since GLib 2.40, when used with `SocketClientExt::connect` or `SocketClientExt::connect_async`, during emission of `SocketClientEvent::Connecting`, this function will return the remote address that will be used for the connection. This allows applications to print e.g. "Connecting to example.com (10.42.77.3)...". # Returns a `SocketAddress` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Gets the underlying `Socket` object of the connection. This can be useful if you want to do something unusual on it not supported by the `SocketConnection` APIs. # Returns a `Socket` or `None` on error. Checks if `self` is connected. This is equivalent to calling `SocketExt::is_connected` on `self`'s underlying `Socket`. # Returns whether `self` is connected The protocol family of a `SocketAddress`. (These values are identical to the system defines `AF_INET`, `AF_INET6` and `AF_UNIX`, if available.) no address family the UNIX domain family the IPv4 family the IPv6 family A `SocketListener` is an object that keeps track of a set of server sockets and helps you accept sockets from any of the socket, either sync or async. Add addresses and ports to listen on using `SocketListenerExt::add_address` and `SocketListenerExt::add_inet_port`. These will be listened on until `SocketListenerExt::close` is called. Dropping your final reference to the `SocketListener` will not cause `SocketListenerExt::close` to be called implicitly, as some references to the `SocketListener` may be held internally. If you want to implement a network server, also look at `SocketService` and `ThreadedSocketService` which are subclasses of `SocketListener` that make this even easier. # Implements [`SocketListenerExt`](trait.SocketListenerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketListenerExtManual`](prelude/trait.SocketListenerExtManual.html) Trait containing all `SocketListener` methods. # Implementors [`SocketListener`](struct.SocketListener.html), [`SocketService`](struct.SocketService.html) Creates a new `SocketListener` with no sockets to listen for. New listeners can be added with e.g. `SocketListenerExt::add_address` or `SocketListenerExt::add_inet_port`. # Returns a new `SocketListener`. Blocks waiting for a client to connect to any of the sockets added to the listener. Returns a `SocketConnection` for the socket that was accepted. If `source_object` is not `None` it will be filled out with the source object specified when the corresponding socket or address was added to the listener. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `source_object` location where `gobject::Object` pointer will be stored, or `None` ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `SocketConnection` on success, `None` on error. This is the asynchronous version of `SocketListenerExt::accept`. When the operation is finished `callback` will be called. You can then call `SocketListenerExt::accept_socket` to get the result of the operation. ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` ## `user_data` user data for the callback Finishes an async accept operation. See `SocketListener::accept_async` ## `result` a `AsyncResult`. ## `source_object` Optional `gobject::Object` identifying this source # Returns a `SocketConnection` on success, `None` on error. Blocks waiting for a client to connect to any of the sockets added to the listener. Returns the `Socket` that was accepted. If you want to accept the high-level `SocketConnection`, not a `Socket`, which is often the case, then you should use `SocketListenerExt::accept` instead. If `source_object` is not `None` it will be filled out with the source object specified when the corresponding socket or address was added to the listener. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `source_object` location where `gobject::Object` pointer will be stored, or `None`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `Socket` on success, `None` on error. This is the asynchronous version of `SocketListenerExt::accept_socket`. When the operation is finished `callback` will be called. You can then call `SocketListenerExt::accept_socket_finish` to get the result of the operation. ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` ## `user_data` user data for the callback Finishes an async accept operation. See `SocketListener::accept_socket_async` ## `result` a `AsyncResult`. ## `source_object` Optional `gobject::Object` identifying this source # Returns a `Socket` on success, `None` on error. Creates a socket of type `type_` and protocol `protocol`, binds it to `address` and adds it to the set of sockets we're accepting sockets from. Note that adding an IPv6 address, depending on the platform, may or may not result in a listener that also accepts IPv4 connections. For more deterministic behavior, see `SocketListenerExt::add_inet_port`. `source_object` will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. If successful and `effective_address` is non-`None` then it will be set to the address that the binding actually occurred at. This is helpful for determining the port number that was used for when requesting a binding to port 0 (ie: "any port"). This address, if requested, belongs to the caller and must be freed. Call `SocketListenerExt::close` to stop listening on `address`; this will not be done automatically when you drop your final reference to `self`, as references may be held internally. ## `address` a `SocketAddress` ## `type_` a `SocketType` ## `protocol` a `SocketProtocol` ## `source_object` Optional `gobject::Object` identifying this source ## `effective_address` location to store the address that was bound to, or `None`. # Returns `true` on success, `false` on error. Listens for TCP connections on any available port number for both IPv6 and IPv4 (if each is available). This is useful if you need to have a socket for incoming connections but don't care about the specific port number. `source_object` will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. ## `source_object` Optional `gobject::Object` identifying this source # Returns the port number, or 0 in case of failure. Helper function for `SocketListenerExt::add_address` that creates a TCP/IP socket listening on IPv4 and IPv6 (if supported) on the specified port on all interfaces. `source_object` will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. Call `SocketListenerExt::close` to stop listening on `port`; this will not be done automatically when you drop your final reference to `self`, as references may be held internally. ## `port` an IP port number (non-zero) ## `source_object` Optional `gobject::Object` identifying this source # Returns `true` on success, `false` on error. Adds `socket` to the set of sockets that we try to accept new clients from. The socket must be bound to a local address and listened to. `source_object` will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. The `socket` will not be automatically closed when the `self` is finalized unless the listener held the final reference to the socket. Before GLib 2.42, the `socket` was automatically closed on finalization of the `self`, even if references to it were held elsewhere. ## `socket` a listening `Socket` ## `source_object` Optional `gobject::Object` identifying this source # Returns `true` on success, `false` on error. Closes all the sockets in the listener. Sets the listen backlog on the sockets in the listener. See `SocketExt::set_listen_backlog` for details ## `listen_backlog` an integer Emitted when `listener`'s activity on `socket` changes state. Note that when `listener` is used to listen on both IPv4 and IPv6, a separate set of signals will be emitted for each, and the order they happen in is undefined. Feature: `v2_46` ## `event` the event that is occurring ## `socket` the `Socket` the event is occurring on Describes an event occurring on a `SocketListener`. See the `SocketListener::event` signal for more details. Additional values may be added to this type in the future. The listener is about to bind a socket. The listener has bound a socket. The listener is about to start listening on this socket. The listener is now listening on this socket. Feature: `v2_46` A protocol identifier is specified when creating a `Socket`, which is a family/type specific identifier, where 0 means the default protocol for the particular family/type. This enum contains a set of commonly available and used protocols. You can also pass any other identifiers handled by the platform in order to use protocols not listed here. The protocol type is unknown The default protocol for the family/type TCP over IP UDP over IP SCTP over IP A `SocketService` is an object that represents a service that is provided to the network or over local sockets. When a new connection is made to the service the `SocketService::incoming` signal is emitted. A `SocketService` is a subclass of `SocketListener` and you need to add the addresses you want to accept connections on with the `SocketListener` APIs. There are two options for implementing a network service based on `SocketService`. The first is to create the service using `SocketService::new` and to connect to the `SocketService::incoming` signal. The second is to subclass `SocketService` and override the default signal handler implementation. In either case, the handler must immediately return, or else it will block additional incoming connections from being serviced. If you are interested in writing connection handlers that contain blocking code then see `ThreadedSocketService`. The socket service runs on the main loop of the [thread-default context][g-main-context-push-thread-default-context] of the thread it is created in, and is not threadsafe in general. However, the calls to start and stop the service are thread-safe so these can be used from threads that handle incoming clients. # Implements [`SocketServiceExt`](trait.SocketServiceExt.html), [`SocketListenerExt`](trait.SocketListenerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketListenerExtManual`](prelude/trait.SocketListenerExtManual.html) Trait containing all `SocketService` methods. # Implementors [`SocketService`](struct.SocketService.html), [`ThreadedSocketService`](struct.ThreadedSocketService.html) Creates a new `SocketService` with no sockets to listen for. New listeners can be added with e.g. `SocketListenerExt::add_address` or `SocketListenerExt::add_inet_port`. New services are created active, there is no need to call `SocketServiceExt::start`, unless `SocketServiceExt::stop` has been called before. # Returns a new `SocketService`. Check whether the service is active or not. An active service will accept new clients that connect, while a non-active service will let connecting clients queue up until the service is started. # Returns `true` if the service is active, `false` otherwise Restarts the service, i.e. start accepting connections from the added sockets when the mainloop runs. This only needs to be called after the service has been stopped from `SocketServiceExt::stop`. This call is thread-safe, so it may be called from a thread handling an incoming client request. Stops the service, i.e. stops accepting connections from the added sockets when the mainloop runs. This call is thread-safe, so it may be called from a thread handling an incoming client request. Note that this only stops accepting new connections; it does not close the listening sockets, and you can call `SocketServiceExt::start` again later to begin listening again. To close the listening sockets, call `SocketListenerExt::close`. (This will happen automatically when the `SocketService` is finalized.) This must be called before calling `SocketListenerExt::close` as the socket service will start accepting connections immediately when a new socket is added. The ::incoming signal is emitted when a new incoming connection to `service` needs to be handled. The handler must initiate the handling of `connection`, but may not block; in essence, asynchronous operations must be used. `connection` will be unreffed once the signal handler returns, so you need to ref it yourself if you are planning to use it. ## `connection` a new `SocketConnection` object ## `source_object` the source_object passed to `SocketListenerExt::add_address` # Returns `true` to stop other handlers from being called Whether the service is currently accepting connections. Feature: `v2_46` Whether the service is currently accepting connections. Feature: `v2_46` Flags used when creating a `Socket`. Some protocols may not implement all the socket types. Type unknown or wrong Reliable connection-based byte streams (e.g. TCP). Connectionless, unreliable datagram passing. (e.g. UDP) Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP). SRV (service) records are used by some network protocols to provide service-specific aliasing and load-balancing. For example, XMPP (Jabber) uses SRV records to locate the XMPP server for a domain; rather than connecting directly to "example.com" or assuming a specific server hostname like "xmpp.example.com", an XMPP client would look up the "xmpp-client" SRV record for "example.com", and then connect to whatever host was pointed to by that record. You can use `ResolverExt::lookup_service` or `ResolverExt::lookup_service_async` to find the `GSrvTargets` for a given service. However, if you are simply planning to connect to the remote service, you can use `NetworkService`'s `SocketConnectable` interface and not need to worry about `SrvTarget` at all. Creates a new `SrvTarget` with the given parameters. You should not need to use this; normally `GSrvTargets` are created by `Resolver`. ## `hostname` the host that the service is running on ## `port` the port that the service is running on ## `priority` the target's priority ## `weight` the target's weight # Returns a new `SrvTarget`. Copies `self` # Returns a copy of `self` Frees `self` Gets `self`'s hostname (in ASCII form; if you are going to present this to the user, you should use `g_hostname_is_ascii_encoded` to check if it contains encoded Unicode segments, and use `g_hostname_to_unicode` to convert it if it does.) # Returns `self`'s hostname Gets `self`'s port # Returns `self`'s port Gets `self`'s priority. You should not need to look at this; `Resolver` already sorts the targets according to the algorithm in RFC 2782. # Returns `self`'s priority Gets `self`'s weight. You should not need to look at this; `Resolver` already sorts the targets according to the algorithm in RFC 2782. # Returns `self`'s weight Sorts `targets` in place according to the algorithm in RFC 2782. ## `targets` a `glib::List` of `SrvTarget` # Returns the head of the sorted list. `Subprocess` allows the creation of and interaction with child processes. Processes can be communicated with using standard GIO-style APIs (ie: `InputStream`, `OutputStream`). There are GIO-style APIs to wait for process termination (ie: cancellable and with an asynchronous variant). There is an API to force a process to terminate, as well as a race-free API for sending UNIX signals to a subprocess. One major advantage that GIO brings over the core GLib library is comprehensive API for asynchronous I/O, such `OutputStreamExt::splice_async`. This makes GSubprocess significantly more powerful and flexible than equivalent APIs in some other languages such as the `subprocess.py` included with Python. For example, using `Subprocess` one could create two child processes, reading standard output from the first, processing it, and writing to the input stream of the second, all without blocking the main loop. A powerful `Subprocess::communicate` API is provided similar to the `communicate()` method of `subprocess.py`. This enables very easy interaction with a subprocess that has been opened with pipes. `Subprocess` defaults to tight control over the file descriptors open in the child process, avoiding dangling-fd issues that are caused by a simple `fork`/`exec`. The only open file descriptors in the spawned process are ones that were explicitly specified by the `Subprocess` API (unless `SubprocessFlags::InheritFds` was specified). `Subprocess` will quickly reap all child processes as they exit, avoiding "zombie processes" remaining around for long periods of time. `Subprocess::wait` can be used to wait for this to happen, but it will happen even without the call being explicitly made. As a matter of principle, `Subprocess` has no API that accepts shell-style space-separated strings. It will, however, match the typical shell behaviour of searching the PATH for executables that do not contain a directory separator in their name. `Subprocess` attempts to have a very simple API for most uses (ie: spawning a subprocess with arguments and support for most typical kinds of input and output redirection). See `Subprocess::new`. The `SubprocessLauncher` API is provided for more complicated cases (advanced types of redirection, environment variable manipulation, change of working directory, child setup functions, etc). A typical use of `Subprocess` will involve calling `Subprocess::new`, followed by `Subprocess::wait_async` or `Subprocess::wait`. After the process exits, the status can be checked using functions such as `Subprocess::get_if_exited` (which are similar to the familiar WIFEXITED-style POSIX macros). # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Create a new process with the given flags and varargs argument list. By default, matching the `g_spawn_async` defaults, the child's stdin will be set to the system null device, and stdout/stderr will be inherited from the parent. You can use `flags` to control this behavior. The argument list must be terminated with `None`. ## `flags` flags that define the behaviour of the subprocess ## `error` return location for an error, or `None` ## `argv0` first commandline argument to pass to the subprocess # Returns A newly created `Subprocess`, or `None` on error (and `error` will be set) Create a new process with the given flags and argument list. The argument list is expected to be `None`-terminated. ## `argv` commandline arguments for the subprocess ## `flags` flags that define the behaviour of the subprocess # Returns A newly created `Subprocess`, or `None` on error (and `error` will be set) Communicate with the subprocess until it terminates, and all input and output has been completed. If `stdin_buf` is given, the subprocess must have been created with `SubprocessFlags::StdinPipe`. The given data is fed to the stdin of the subprocess and the pipe is closed (ie: EOF). At the same time (as not to cause blocking when dealing with large amounts of data), if `SubprocessFlags::StdoutPipe` or `SubprocessFlags::StderrPipe` were used, reads from those streams. The data that was read is returned in `stdout` and/or the `stderr`. If the subprocess was created with `SubprocessFlags::StdoutPipe`, `stdout_buf` will contain the data read from stdout. Otherwise, for subprocesses not created with `SubprocessFlags::StdoutPipe`, `stdout_buf` will be set to `None`. Similar provisions apply to `stderr_buf` and `SubprocessFlags::StderrPipe`. As usual, any output variable may be given as `None` to ignore it. If you desire the stdout and stderr data to be interleaved, create the subprocess with `SubprocessFlags::StdoutPipe` and `SubprocessFlags::StderrMerge`. The merged result will be returned in `stdout_buf` and `stderr_buf` will be set to `None`. In case of any error (including cancellation), `false` will be returned with `error` set. Some or all of the stdin data may have been written. Any stdout or stderr data that has been read will be discarded. None of the out variables (aside from `error`) will have been set to anything in particular and should not be inspected. In the case that `true` is returned, the subprocess has exited and the exit status inspection APIs (eg: `Subprocess::get_if_exited`, `Subprocess::get_exit_status`) may be used. You should not attempt to use any of the subprocess pipes after starting this function, since they may be left in strange states, even if the operation was cancelled. You should especially not attempt to interact with the pipes while the operation is in progress (either from another thread or if using the asynchronous version). ## `stdin_buf` data to send to the stdin of the subprocess, or `None` ## `cancellable` a `Cancellable` ## `stdout_buf` data read from the subprocess stdout ## `stderr_buf` data read from the subprocess stderr # Returns `true` if successful Asynchronous version of `Subprocess::communicate`. Complete invocation with `Subprocess::communicate_finish`. ## `stdin_buf` Input data, or `None` ## `cancellable` Cancellable ## `callback` Callback ## `user_data` User data Complete an invocation of `Subprocess::communicate_async`. ## `result` Result ## `stdout_buf` Return location for stdout data ## `stderr_buf` Return location for stderr data Like `Subprocess::communicate`, but validates the output of the process as UTF-8, and returns it as a regular NUL terminated string. ## `stdin_buf` data to send to the stdin of the subprocess, or `None` ## `cancellable` a `Cancellable` ## `stdout_buf` data read from the subprocess stdout ## `stderr_buf` data read from the subprocess stderr Asynchronous version of `Subprocess::communicate_utf8`. Complete invocation with `Subprocess::communicate_utf8_finish`. ## `stdin_buf` Input data, or `None` ## `cancellable` Cancellable ## `callback` Callback ## `user_data` User data Complete an invocation of `Subprocess::communicate_utf8_async`. ## `result` Result ## `stdout_buf` Return location for stdout data ## `stderr_buf` Return location for stderr data Use an operating-system specific method to attempt an immediate, forceful termination of the process. There is no mechanism to determine whether or not the request itself was successful; however, you can use `Subprocess::wait` to monitor the status of the process after calling this function. On Unix, this function sends `SIGKILL`. Check the exit status of the subprocess, given that it exited normally. This is the value passed to the `exit` system call or the return value from main. This is equivalent to the system WEXITSTATUS macro. It is an error to call this function before `Subprocess::wait` and unless `Subprocess::get_if_exited` returned `true`. # Returns the exit status On UNIX, returns the process ID as a decimal string. On Windows, returns the result of GetProcessId() also as a string. Check if the given subprocess exited normally (ie: by way of `exit` or return from `main`). This is equivalent to the system WIFEXITED macro. It is an error to call this function before `Subprocess::wait` has returned. # Returns `true` if the case of a normal exit Check if the given subprocess terminated in response to a signal. This is equivalent to the system WIFSIGNALED macro. It is an error to call this function before `Subprocess::wait` has returned. # Returns `true` if the case of termination due to a signal Gets the raw status code of the process, as from `waitpid`. This value has no particular meaning, but it can be used with the macros defined by the system headers such as WIFEXITED. It can also be used with `g_spawn_check_exit_status`. It is more likely that you want to use `Subprocess::get_if_exited` followed by `Subprocess::get_exit_status`. It is an error to call this function before `Subprocess::wait` has returned. # Returns the (meaningless) `waitpid` exit status from the kernel Gets the `InputStream` from which to read the stderr output of `self`. The process must have been created with `SubprocessFlags::StderrPipe`. # Returns the stderr pipe Gets the `OutputStream` that you can write to in order to give data to the stdin of `self`. The process must have been created with `SubprocessFlags::StdinPipe`. # Returns the stdout pipe Gets the `InputStream` from which to read the stdout output of `self`. The process must have been created with `SubprocessFlags::StdoutPipe`. # Returns the stdout pipe Checks if the process was "successful". A process is considered successful if it exited cleanly with an exit status of 0, either by way of the `exit` system call or return from `main`. It is an error to call this function before `Subprocess::wait` has returned. # Returns `true` if the process exited cleanly with a exit status of 0 Get the signal number that caused the subprocess to terminate, given that it terminated due to a signal. This is equivalent to the system WTERMSIG macro. It is an error to call this function before `Subprocess::wait` and unless `Subprocess::get_if_signaled` returned `true`. # Returns the signal causing termination Sends the UNIX signal `signal_num` to the subprocess, if it is still running. This API is race-free. If the subprocess has terminated, it will not be signalled. This API is not available on Windows. ## `signal_num` the signal number to send Synchronously wait for the subprocess to terminate. After the process terminates you can query its exit status with functions such as `Subprocess::get_if_exited` and `Subprocess::get_exit_status`. This function does not fail in the case of the subprocess having abnormal termination. See `Subprocess::wait_check` for that. Cancelling `cancellable` doesn't kill the subprocess. Call `Subprocess::force_exit` if it is desirable. ## `cancellable` a `Cancellable` # Returns `true` on success, `false` if `cancellable` was cancelled Wait for the subprocess to terminate. This is the asynchronous version of `Subprocess::wait`. ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` to call when the operation is complete ## `user_data` user_data for `callback` Combines `Subprocess::wait` with `g_spawn_check_exit_status`. ## `cancellable` a `Cancellable` # Returns `true` on success, `false` if process exited abnormally, or `cancellable` was cancelled Combines `Subprocess::wait_async` with `g_spawn_check_exit_status`. This is the asynchronous version of `Subprocess::wait_check`. ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` to call when the operation is complete ## `user_data` user_data for `callback` Collects the result of a previous call to `Subprocess::wait_check_async`. ## `result` the `AsyncResult` passed to your `GAsyncReadyCallback` # Returns `true` if successful, or `false` with `error` set Collects the result of a previous call to `Subprocess::wait_async`. ## `result` the `AsyncResult` passed to your `GAsyncReadyCallback` # Returns `true` if successful, or `false` with `error` set This class contains a set of options for launching child processes, such as where its standard input and output will be directed, the argument list, the environment, and more. While the `Subprocess` class has high level functions covering popular cases, use of this class allows access to more advanced options. It can also be used to launch multiple subprocesses with a similar configuration. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `SubprocessLauncher`. The launcher is created with the default options. A copy of the environment of the calling process is made at the time of this call and will be used as the environment that the process is launched in. ## `flags` `SubprocessFlags` Returns the value of the environment variable `variable` in the environment of processes launched from this launcher. On UNIX, the returned string can be an arbitrary byte string. On Windows, it will be UTF-8. ## `variable` the environment variable to get # Returns the value of the environment variable, `None` if unset Sets up a child setup function. The child setup function will be called after `fork` but before `exec` on the child's side. `destroy_notify` will not be automatically called on the child's side of the `fork`. It will only be called when the last reference on the `SubprocessLauncher` is dropped or when a new child setup function is given. `None` can be given as `child_setup` to disable the functionality. Child setup functions are only available on UNIX. ## `child_setup` a `GSpawnChildSetupFunc` to use as the child setup function ## `user_data` user data for `child_setup` ## `destroy_notify` a `GDestroyNotify` for `user_data` Sets the current working directory that processes will be launched with. By default processes are launched with the current working directory of the launching process at the time of launch. ## `cwd` the cwd for launched processes Replace the entire environment of processes launched from this launcher with the given 'environ' variable. Typically you will build this variable by using `g_listenv` to copy the process 'environ' and using the functions `g_environ_setenv`, `g_environ_unsetenv`, etc. As an alternative, you can use `SubprocessLauncher::setenv`, `SubprocessLauncher::unsetenv`, etc. Pass an empty array to set an empty environment. Pass `None` to inherit the parent process’ environment. As of GLib 2.54, the parent process’ environment will be copied when `SubprocessLauncher::set_environ` is called. Previously, it was copied when the subprocess was executed. This means the copied environment may now be modified (using `SubprocessLauncher::setenv`, etc.) before launching the subprocess. On UNIX, all strings in this array can be arbitrary byte strings. On Windows, they should be in UTF-8. ## `env` the replacement environment Sets the flags on the launcher. The default flags are `SubprocessFlags::None`. You may not set flags that specify conflicting options for how to handle a particular stdio stream (eg: specifying both `SubprocessFlags::StdinPipe` and `SubprocessFlags::StdinInherit`). You may also not set a flag that conflicts with a previous call to a function like `SubprocessLauncher::set_stdin_file_path` or `SubprocessLauncher::take_stdout_fd`. ## `flags` `SubprocessFlags` Sets the file path to use as the stderr for spawned processes. If `path` is `None` then any previously given path is unset. The file will be created or truncated when the process is spawned, as would be the case if using '2>' at the shell. If you want to send both stdout and stderr to the same file then use `SubprocessFlags::StderrMerge`. You may not set a stderr file path if a stderr fd is already set or if the launcher flags contain any flags directing stderr elsewhere. This feature is only available on UNIX. ## `path` a filename or `None` Sets the file path to use as the stdin for spawned processes. If `path` is `None` then any previously given path is unset. The file must exist or spawning the process will fail. You may not set a stdin file path if a stdin fd is already set or if the launcher flags contain any flags directing stdin elsewhere. This feature is only available on UNIX. Sets the file path to use as the stdout for spawned processes. If `path` is `None` then any previously given path is unset. The file will be created or truncated when the process is spawned, as would be the case if using '>' at the shell. You may not set a stdout file path if a stdout fd is already set or if the launcher flags contain any flags directing stdout elsewhere. This feature is only available on UNIX. ## `path` a filename or `None` Sets the environment variable `variable` in the environment of processes launched from this launcher. On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name cannot contain '='. On Windows, they should be in UTF-8. ## `variable` the environment variable to set, must not contain '=' ## `value` the new value for the variable ## `overwrite` whether to change the variable if it already exists Creates a `Subprocess` given a provided varargs list of arguments. ## `error` Error ## `argv0` Command line arguments # Returns A new `Subprocess`, or `None` on error (and `error` will be set) Creates a `Subprocess` given a provided array of arguments. ## `argv` Command line arguments # Returns A new `Subprocess`, or `None` on error (and `error` will be set) Transfer an arbitrary file descriptor from parent process to the child. This function takes "ownership" of the fd; it will be closed in the parent when `self` is freed. By default, all file descriptors from the parent will be closed. This function allows you to create (for example) a custom `pipe` or `socketpair` before launching the process, and choose the target descriptor in the child. An example use case is GNUPG, which has a command line argument --passphrase-fd providing a file descriptor number where it expects the passphrase to be written. ## `source_fd` File descriptor in parent process ## `target_fd` Target descriptor for child process Sets the file descriptor to use as the stderr for spawned processes. If `fd` is -1 then any previously given fd is unset. Note that the default behaviour is to pass stderr through to the stderr of the parent process. The passed `fd` belongs to the `SubprocessLauncher`. It will be automatically closed when the launcher is finalized. The file descriptor will also be closed on the child side when executing the spawned process. You may not set a stderr fd if a stderr file path is already set or if the launcher flags contain any flags directing stderr elsewhere. This feature is only available on UNIX. ## `fd` a file descriptor, or -1 Sets the file descriptor to use as the stdin for spawned processes. If `fd` is -1 then any previously given fd is unset. Note that if your intention is to have the stdin of the calling process inherited by the child then `SubprocessFlags::StdinInherit` is a better way to go about doing that. The passed `fd` is noted but will not be touched in the current process. It is therefore necessary that it be kept open by the caller until the subprocess is spawned. The file descriptor will also not be explicitly closed on the child side, so it must be marked O_CLOEXEC if that's what you want. You may not set a stdin fd if a stdin file path is already set or if the launcher flags contain any flags directing stdin elsewhere. This feature is only available on UNIX. ## `fd` a file descriptor, or -1 Sets the file descriptor to use as the stdout for spawned processes. If `fd` is -1 then any previously given fd is unset. Note that the default behaviour is to pass stdout through to the stdout of the parent process. The passed `fd` is noted but will not be touched in the current process. It is therefore necessary that it be kept open by the caller until the subprocess is spawned. The file descriptor will also not be explicitly closed on the child side, so it must be marked O_CLOEXEC if that's what you want. You may not set a stdout fd if a stdout file path is already set or if the launcher flags contain any flags directing stdout elsewhere. This feature is only available on UNIX. ## `fd` a file descriptor, or -1 Removes the environment variable `variable` from the environment of processes launched from this launcher. On UNIX, the variable's name can be an arbitrary byte string not containing '='. On Windows, it should be in UTF-8. ## `variable` the environment variable to unset, must not contain '=' This is the subclass of `SocketConnection` that is created for TCP/IP sockets. # Implements [`TcpConnectionExt`](trait.TcpConnectionExt.html), [`SocketConnectionExt`](trait.SocketConnectionExt.html), [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TcpConnection` methods. # Implementors [`TcpConnection`](struct.TcpConnection.html) Checks if graceful disconnects are used. See `TcpConnectionExt::set_graceful_disconnect`. # Returns `true` if graceful disconnect is used on close, `false` otherwise This enables graceful disconnects on close. A graceful disconnect means that we signal the receiving end that the connection is terminated and wait for it to close the connection before closing the connection. A graceful disconnect means that we can be sure that we successfully sent all the outstanding data to the other end, or get an error reported. However, it also means we have to wait for all the data to reach the other side and for it to acknowledge this by closing the socket, which may take a while. For this reason it is disabled by default. ## `graceful_disconnect` Whether to do graceful disconnects or not `ThemedIcon` is an implementation of `Icon` that supports icon themes. `ThemedIcon` contains a list of all of the icons present in an icon theme, so that icons can be looked up quickly. `ThemedIcon` does not provide actual pixmaps for icons, just the icon names. Ideally something like `gtk_icon_theme_choose_icon` should be used to resolve the list of names so that fallback icons work nicely with themes that inherit other themes. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IconExt`](trait.IconExt.html) Creates a new themed icon for `iconname`. ## `iconname` a string containing an icon name. # Returns a new `ThemedIcon`. Creates a new themed icon for `iconnames`. ## `iconnames` an array of strings containing icon names. ## `len` the length of the `iconnames` array, or -1 if `iconnames` is `None`-terminated # Returns a new `ThemedIcon` Creates a new themed icon for `iconname`, and all the names that can be created by shortening `iconname` at '-' characters. In the following example, `icon1` and `icon2` are equivalent: ```C const char *names[] = { "gnome-dev-cdrom-audio", "gnome-dev-cdrom", "gnome-dev", "gnome" }; icon1 = g_themed_icon_new_from_names (names, 4); icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio"); ``` ## `iconname` a string containing an icon name # Returns a new `ThemedIcon`. Append a name to the list of icons from within `self`. Note that doing so invalidates the hash computed by prior calls to `Icon::hash`. ## `iconname` name of icon to append to list of icons from within `self`. Gets the names of icons from within `self`. # Returns a list of icon names. Prepend a name to the list of icons from within `self`. Note that doing so invalidates the hash computed by prior calls to `Icon::hash`. ## `iconname` name of icon to prepend to list of icons from within `self`. The icon name. A `None`-terminated array of icon names. A `None`-terminated array of icon names. Whether to use the default fallbacks found by shortening the icon name at '-' characters. If the "names" array has more than one element, ignores any past the first. For example, if the icon name was "gnome-dev-cdrom-audio", the array would become ```C { "gnome-dev-cdrom-audio", "gnome-dev-cdrom", "gnome-dev", "gnome", NULL }; ``` Whether to use the default fallbacks found by shortening the icon name at '-' characters. If the "names" array has more than one element, ignores any past the first. For example, if the icon name was "gnome-dev-cdrom-audio", the array would become ```C { "gnome-dev-cdrom-audio", "gnome-dev-cdrom", "gnome-dev", "gnome", NULL }; ``` A `ThreadedSocketService` is a simple subclass of `SocketService` that handles incoming connections by creating a worker thread and dispatching the connection to it by emitting the `ThreadedSocketService::run` signal in the new thread. The signal handler may perform blocking IO and need not return until the connection is closed. The service is implemented using a thread pool, so there is a limited amount of threads available to serve incoming requests. The service automatically stops the `SocketService` from accepting new connections when all threads are busy. As with `SocketService`, you may connect to `ThreadedSocketService::run`, or subclass and override the default handler. # Implements [`ThreadedSocketServiceExt`](trait.ThreadedSocketServiceExt.html), [`SocketServiceExt`](trait.SocketServiceExt.html), [`SocketListenerExt`](trait.SocketListenerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketListenerExtManual`](prelude/trait.SocketListenerExtManual.html) Trait containing all `ThreadedSocketService` methods. # Implementors [`ThreadedSocketService`](struct.ThreadedSocketService.html) Creates a new `ThreadedSocketService` with no listeners. Listeners must be added with one of the `SocketListener` "add" methods. ## `max_threads` the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit # Returns a new `SocketService`. The ::run signal is emitted in a worker thread in response to an incoming connection. This thread is dedicated to handling `connection` and may perform blocking IO. The signal handler need not return until the connection is closed. ## `connection` a new `SocketConnection` object. ## `source_object` the source_object passed to `SocketListenerExt::add_address`. # Returns `true` to stop further signal handlers from being called The client authentication mode for a `TlsServerConnection`. client authentication not required client authentication is requested client authentication is required A certificate used for TLS authentication and encryption. This can represent either a certificate only (eg, the certificate received by a client from a server), or the combination of a certificate and a private key (which is needed when acting as a `TlsServerConnection`). # Implements [`TlsCertificateExt`](trait.TlsCertificateExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TlsCertificate` methods. # Implementors [`TlsCertificate`](struct.TlsCertificate.html) Creates a `TlsCertificate` from the PEM-encoded data in `file`. The returned certificate will be the first certificate found in `file`. As of GLib 2.44, if `file` contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the `TlsCertificate:issuer` property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned. If `file` cannot be read or parsed, the function will return `None` and set `error`. Otherwise, this behaves like `TlsCertificate::new_from_pem`. ## `file` file containing a PEM-encoded certificate to import # Returns the new certificate, or `None` on error Creates a `TlsCertificate` from the PEM-encoded data in `cert_file` and `key_file`. The returned certificate will be the first certificate found in `cert_file`. As of GLib 2.44, if `cert_file` contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the `TlsCertificate:issuer` property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned. If either file cannot be read or parsed, the function will return `None` and set `error`. Otherwise, this behaves like `TlsCertificate::new_from_pem`. ## `cert_file` file containing one or more PEM-encoded certificates to import ## `key_file` file containing a PEM-encoded private key to import # Returns the new certificate, or `None` on error Creates a `TlsCertificate` from the PEM-encoded data in `data`. If `data` includes both a certificate and a private key, then the returned certificate will include the private key data as well. (See the `TlsCertificate:private-key-pem` property for information about supported formats.) The returned certificate will be the first certificate found in `data`. As of GLib 2.44, if `data` contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the `TlsCertificate:issuer` property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned. ## `data` PEM-encoded certificate data ## `length` the length of `data`, or -1 if it's 0-terminated. # Returns the new certificate, or `None` if `data` is invalid Creates one or more `GTlsCertificates` from the PEM-encoded data in `file`. If `file` cannot be read or parsed, the function will return `None` and set `error`. If `file` does not contain any PEM-encoded certificates, this will return an empty list and not set `error`. ## `file` file containing PEM-encoded certificates to import # Returns a `glib::List` containing `TlsCertificate` objects. You must free the list and its contents when you are done with it. Gets the `TlsCertificate` representing `self`'s issuer, if known # Returns The certificate of `self`'s issuer, or `None` if `self` is self-signed or signed with an unknown certificate. Check if two `TlsCertificate` objects represent the same certificate. The raw DER byte data of the two certificates are checked for equality. This has the effect that two certificates may compare equal even if their `TlsCertificate:issuer`, `TlsCertificate:private-key`, or `TlsCertificate:private-key-pem` properties differ. ## `cert_two` second certificate to compare # Returns whether the same or not This verifies `self` and returns a set of `TlsCertificateFlags` indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system CA database. If `identity` is not `None`, `self`'s name(s) will be compared against it, and `TlsCertificateFlags::BadIdentity` will be set in the return value if it does not match. If `identity` is `None`, that bit will never be set in the return value. If `trusted_ca` is not `None`, then `self` (or one of the certificates in its chain) must be signed by it, or else `TlsCertificateFlags::UnknownCa` will be set in the return value. If `trusted_ca` is `None`, that bit will never be set in the return value. (All other `TlsCertificateFlags` values will always be set or unset as appropriate.) ## `identity` the expected peer identity ## `trusted_ca` the certificate of a trusted authority # Returns the appropriate `TlsCertificateFlags` The DER (binary) encoded representation of the certificate. This property and the `TlsCertificate:certificate-pem` property represent the same data, just in different forms. The DER (binary) encoded representation of the certificate. This property and the `TlsCertificate:certificate-pem` property represent the same data, just in different forms. The PEM (ASCII) encoded representation of the certificate. This property and the `TlsCertificate:certificate` property represent the same data, just in different forms. The PEM (ASCII) encoded representation of the certificate. This property and the `TlsCertificate:certificate` property represent the same data, just in different forms. A `TlsCertificate` representing the entity that issued this certificate. If `None`, this means that the certificate is either self-signed, or else the certificate of the issuer is not available. A `TlsCertificate` representing the entity that issued this certificate. If `None`, this means that the certificate is either self-signed, or else the certificate of the issuer is not available. The DER (binary) encoded representation of the certificate's private key, in either PKCS`1` format or unencrypted PKCS`8` format. This property (or the `TlsCertificate:private-key-pem` property) can be set when constructing a key (eg, from a file), but cannot be read. PKCS`8` format is supported since 2.32; earlier releases only support PKCS`1`. You can use the `openssl rsa` tool to convert PKCS`8` keys to PKCS`1`. The PEM (ASCII) encoded representation of the certificate's private key in either PKCS`1` format ("`BEGIN RSA PRIVATE KEY`") or unencrypted PKCS`8` format ("`BEGIN PRIVATE KEY`"). This property (or the `TlsCertificate:private-key` property) can be set when constructing a key (eg, from a file), but cannot be read. PKCS`8` format is supported since 2.32; earlier releases only support PKCS`1`. You can use the `openssl rsa` tool to convert PKCS`8` keys to PKCS`1`. Flags for `TlsInteractionExt::request_certificate`, `TlsInteractionExt::request_certificate_async`, and `TlsInteractionExt::invoke_request_certificate`. No flags `TlsClientConnection` is the client-side subclass of `TlsConnection`, representing a client-side TLS connection. # Implements [`TlsClientConnectionExt`](trait.TlsClientConnectionExt.html), [`TlsConnectionExt`](trait.TlsConnectionExt.html), [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TlsClientConnection` methods. # Implementors [`TlsClientConnection`](struct.TlsClientConnection.html) Creates a new `TlsClientConnection` wrapping `base_io_stream` (which must have pollable input and output streams) which is assumed to communicate with the server identified by `server_identity`. See the documentation for `TlsConnection:base-io-stream` for restrictions on when application code can run operations on the `base_io_stream` after this function has returned. ## `base_io_stream` the `IOStream` to wrap ## `server_identity` the expected identity of the server # Returns the new `TlsClientConnection`, or `None` on error Copies session state from one connection to another. This is not normally needed, but may be used when the same session needs to be used between different endpoints as is required by some protocols such as FTP over TLS. `source` should have already completed a handshake, and `self` should not have completed a handshake. Feature: `v2_46` ## `source` a `TlsClientConnection` Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. Otherwise, it will be `None`. Each item in the list is a `glib::ByteArray` which contains the complete subject DN of the certificate authority. # Returns the list of CA DNs. You should unref each element with `glib::ByteArray::unref` and then the free the list with `glib::List::free`. Gets `self`'s expected server identity # Returns a `SocketConnectable` describing the expected server identity, or `None` if the expected identity is not known. Gets whether `self` will force the lowest-supported TLS protocol version rather than attempt to negotiate the highest mutually- supported version of TLS; see `TlsClientConnection::set_use_ssl3`. # Deprecated since 2.56 SSL 3.0 is insecure, and this function does not actually indicate whether it is enabled. # Returns whether `self` will use the lowest-supported TLS protocol version Gets `self`'s validation flags # Returns the validation flags Sets `self`'s expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let `self` know what name to look for in the certificate when performing `TlsCertificateFlags::BadIdentity` validation, if enabled. ## `identity` a `SocketConnectable` describing the expected server identity Since 2.42.1, if `use_ssl3` is `true`, this forces `self` to use the lowest-supported TLS protocol version rather than trying to properly negotiate the highest mutually-supported protocol version with the peer. Be aware that SSL 3.0 is generally disabled by the `TlsBackend`, so the lowest-supported protocol version is probably not SSL 3.0. Since 2.58, this may additionally cause an RFC 7507 fallback SCSV to be sent to the server, causing modern TLS servers to immediately terminate the connection. You should generally only use this function if you need to connect to broken servers that exhibit TLS protocol version intolerance, and when an initial attempt to connect to a server normally has already failed. # Deprecated since 2.56 SSL 3.0 is insecure, and this function does not generally enable or disable it, despite its name. ## `use_ssl3` whether to use the lowest-supported protocol version Sets `self`'s validation flags, to override the default set of checks performed when validating a server certificate. By default, `TlsCertificateFlags::ValidateAll` is used. ## `flags` the `TlsCertificateFlags` to use A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes. Each item in the list is a `glib::ByteArray` which contains the complete subject DN of the certificate authority. A `SocketConnectable` describing the identity of the server that is expected on the other end of the connection. If the `TlsCertificateFlags::BadIdentity` flag is set in `TlsClientConnection:validation-flags`, this object will be used to determine the expected identify of the remote end of the connection; if `TlsClientConnection:server-identity` is not set, or does not match the identity presented by the server, then the `TlsCertificateFlags::BadIdentity` validation will fail. In addition to its use in verifying the server certificate, this is also used to give a hint to the server about what certificate we expect, which is useful for servers that serve virtual hosts. A `SocketConnectable` describing the identity of the server that is expected on the other end of the connection. If the `TlsCertificateFlags::BadIdentity` flag is set in `TlsClientConnection:validation-flags`, this object will be used to determine the expected identify of the remote end of the connection; if `TlsClientConnection:server-identity` is not set, or does not match the identity presented by the server, then the `TlsCertificateFlags::BadIdentity` validation will fail. In addition to its use in verifying the server certificate, this is also used to give a hint to the server about what certificate we expect, which is useful for servers that serve virtual hosts. If `true`, forces the connection to use a fallback version of TLS or SSL, rather than trying to negotiate the best version of TLS to use. See `TlsClientConnection::set_use_ssl3`. # Deprecated since 2.56 SSL 3.0 is insecure, and this property does not generally enable or disable it, despite its name. If `true`, forces the connection to use a fallback version of TLS or SSL, rather than trying to negotiate the best version of TLS to use. See `TlsClientConnection::set_use_ssl3`. # Deprecated since 2.56 SSL 3.0 is insecure, and this property does not generally enable or disable it, despite its name. What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in all of the ways indicated here will be rejected unless the application overrides the default via `TlsConnection::accept-certificate`. What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in all of the ways indicated here will be rejected unless the application overrides the default via `TlsConnection::accept-certificate`. `TlsConnection` is the base TLS connection class type, which wraps a `IOStream` and provides TLS encryption on top of it. Its subclasses, `TlsClientConnection` and `TlsServerConnection`, implement client-side and server-side TLS, respectively. For DTLS (Datagram TLS) support, see `DtlsConnection`. # Implements [`TlsConnectionExt`](trait.TlsConnectionExt.html), [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TlsConnection` methods. # Implementors [`TlsClientConnection`](struct.TlsClientConnection.html), [`TlsConnection`](struct.TlsConnection.html), [`TlsServerConnection`](struct.TlsServerConnection.html) Used by `TlsConnection` implementations to emit the `TlsConnection::accept-certificate` signal. ## `peer_cert` the peer's `TlsCertificate` ## `errors` the problems with `peer_cert` # Returns `true` if one of the signal handlers has returned `true` to accept `peer_cert` Gets `self`'s certificate, as set by `TlsConnectionExt::set_certificate`. # Returns `self`'s certificate, or `None` Gets the certificate database that `self` uses to verify peer certificates. See `TlsConnectionExt::set_database`. # Returns the certificate database that `self` uses or `None` Get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If `None` is returned, then no user interaction will occur for this connection. # Returns The interaction object. Gets `self`'s peer's certificate after the handshake has completed. (It is not set during the emission of `TlsConnection::accept-certificate`.) # Returns `self`'s peer's certificate, or `None` Gets the errors associated with validating `self`'s peer's certificate, after the handshake has completed. (It is not set during the emission of `TlsConnection::accept-certificate`.) # Returns `self`'s peer's certificate errors Gets `self` rehandshaking mode. See `TlsConnectionExt::set_rehandshake_mode` for details. # Returns `self`'s rehandshaking mode Tests whether or not `self` expects a proper TLS close notification when the connection is closed. See `TlsConnectionExt::set_require_close_notify` for details. # Returns `true` if `self` requires a proper TLS close notification. Attempts a TLS handshake on `self`. On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after connecting (or after sending a "STARTTLS"-type command) and may need to rehandshake later if the server requests it, `TlsConnection` will handle this for you automatically when you try to send or receive data on the connection. However, you can call `TlsConnectionExt::handshake` manually if you want to know for sure whether the initial handshake succeeded or failed (as opposed to just immediately trying to write to `self`'s output stream, in which case if it fails, it may not be possible to tell if it failed before or after completing the handshake). Likewise, on the server side, although a handshake is necessary at the beginning of the communication, you do not need to call this function explicitly unless you want clearer error reporting. However, you may call `TlsConnectionExt::handshake` later on to rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, the behavior is undefined but guaranteed to be reasonable and nondestructive, so most older code should be expected to continue to work without changes. `TlsConnection::accept_certificate` may be emitted during the handshake. ## `cancellable` a `Cancellable`, or `None` # Returns success or failure Asynchronously performs a TLS handshake on `self`. See `TlsConnectionExt::handshake` for more information. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call when the handshake is complete ## `user_data` the data to pass to the callback function Finish an asynchronous TLS handshake operation. See `TlsConnectionExt::handshake` for more information. ## `result` a `AsyncResult`. # Returns `true` on success, `false` on failure, in which case `error` will be set. This sets the certificate that `self` will present to its peer during the TLS handshake. For a `TlsServerConnection`, it is mandatory to set this, and that will normally be done at construct time. For a `TlsClientConnection`, this is optional. If a handshake fails with `TlsError::CertificateRequired`, that means that the server requires a certificate, and if you try connecting again, you should call this method first. You can call `TlsClientConnection::get_accepted_cas` on the failed connection to get a list of Certificate Authorities that the server will accept certificates from. (It is also possible that a server will allow the connection with or without a certificate; in that case, if you don't provide a certificate, you can tell that the server requested one by the fact that `TlsClientConnection::get_accepted_cas` will return non-`None`.) ## `certificate` the certificate to use for `self` Sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See `TlsBackend::get_default_database`. If set to `None`, then peer certificate validation will always set the `TlsCertificateFlags::UnknownCa` error (meaning `TlsConnection::accept-certificate` will always be emitted on client-side connections, unless that bit is not set in `TlsClientConnection:validation-flags`). ## `database` a `TlsDatabase` Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. The `interaction` argument will normally be a derived subclass of `TlsInteraction`. `None` can also be provided if no user interaction should occur for this connection. ## `interaction` an interaction object, or `None` Sets how `self` behaves with respect to rehandshaking requests, when TLS 1.2 or older is in use. `TlsRehandshakeMode::Never` means that it will never agree to rehandshake after the initial handshake is complete. (For a client, this means it will refuse rehandshake requests from the server, and for a server, this means it will close the connection with an error if the client attempts to rehandshake.) `TlsRehandshakeMode::Safely` means that the connection will allow a rehandshake only if the other end of the connection supports the TLS `renegotiation_info` extension. This is the default behavior, but means that rehandshaking will not work against older implementations that do not support that extension. `TlsRehandshakeMode::Unsafely` means that the connection will allow rehandshaking even without the `renegotiation_info` extension. On the server side in particular, this is not recommended, since it leaves the server open to certain attacks. However, this mode is necessary if you need to allow renegotiation with older client software. ## `mode` the rehandshaking mode Sets whether or not `self` expects a proper TLS close notification before the connection is closed. If this is `true` (the default), then `self` will expect to receive a TLS close notification from its peer before the connection is closed, and will return a `TlsError::Eof` error if the connection is closed without proper notification (since this may indicate a network error, or man-in-the-middle attack). In some protocols, the application will know whether or not the connection was closed cleanly based on application-level data (because the application-level data includes a length field, or is somehow self-delimiting); in this case, the close notify is redundant and sometimes omitted. (TLS 1.1 explicitly allows this; in TLS 1.0 it is technically an error, but often done anyway.) You can use `TlsConnectionExt::set_require_close_notify` to tell `self` to allow an "unannounced" connection close, in which case the close will show up as a 0-length read, as in a non-TLS `SocketConnection`, and it is up to the application to check that the data has been fully received. Note that this only affects the behavior when the peer closes the connection; when the application calls `IOStreamExt::close` itself on `self`, this will send a close notification regardless of the setting of this property. If you explicitly want to do an unclean close, you can close `self`'s `TlsConnection:base-io-stream` rather than closing `self` itself, but note that this may only be done when no other operations are pending on `self` or the base I/O stream. ## `require_close_notify` whether or not to require close notification Emitted during the TLS handshake after the peer certificate has been received. You can examine `peer_cert`'s certification path by calling `TlsCertificateExt::get_issuer` on it. For a client-side connection, `peer_cert` is the server's certificate, and the signal will only be emitted if the certificate was not acceptable according to `conn`'s `TlsClientConnection:validation_flags`. If you would like the certificate to be accepted despite `errors`, return `true` from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with `TlsError::BadCertificate`. For a server-side connection, `peer_cert` is the certificate presented by the client, if this was requested via the server's `TlsServerConnection:authentication_mode`. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns `true`. Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return `false` from the signal handler on the first attempt, and then after the connection attempt returns a `TlsError::Handshake`, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return `true` from the signal handler the next time. If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer. ## `peer_cert` the peer's `TlsCertificate` ## `errors` the problems with `peer_cert`. # Returns `true` to accept `peer_cert` (which will also immediately end the signal emission). `false` to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. The `IOStream` that the connection wraps. The connection holds a reference to this stream, and may run operations on the stream from other threads throughout its lifetime. Consequently, after the `IOStream` has been constructed, application code may only run its own operations on this stream when no `IOStream` operations are running. The `IOStream` that the connection wraps. The connection holds a reference to this stream, and may run operations on the stream from other threads throughout its lifetime. Consequently, after the `IOStream` has been constructed, application code may only run its own operations on this stream when no `IOStream` operations are running. The connection's certificate; see `TlsConnectionExt::set_certificate`. The connection's certificate; see `TlsConnectionExt::set_certificate`. The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See `TlsBackend::get_default_database`. The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See `TlsBackend::get_default_database`. A `TlsInteraction` object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. A `TlsInteraction` object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. The connection's peer's certificate, after the TLS handshake has completed and the certificate has been accepted. Note in particular that this is not yet set during the emission of `TlsConnection::accept-certificate`. (You can watch for a `gobject::Object::notify` signal on this property to detect when a handshake has occurred.) The errors noticed-and-ignored while verifying `TlsConnection:peer-certificate`. Normally this should be 0, but it may not be if `TlsClientConnection:validation-flags` is not `TlsCertificateFlags::ValidateAll`, or if `TlsConnection::accept-certificate` overrode the default behavior. The rehandshaking mode. See `TlsConnectionExt::set_rehandshake_mode`. The rehandshaking mode. See `TlsConnectionExt::set_rehandshake_mode`. Whether or not proper TLS close notification is required. See `TlsConnectionExt::set_require_close_notify`. Whether or not proper TLS close notification is required. See `TlsConnectionExt::set_require_close_notify`. `TlsDatabase` is used to lookup certificates and other information from a certificate or key store. It is an abstract base class which TLS library specific subtypes override. Most common client applications will not directly interact with `TlsDatabase`. It is used internally by `TlsConnection`. # Implements [`TlsDatabaseExt`](trait.TlsDatabaseExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TlsDatabase` methods. # Implementors [`TlsDatabase`](struct.TlsDatabase.html), [`TlsFileDatabase`](struct.TlsFileDatabase.html) Create a handle string for the certificate. The database will only be able to create a handle for certificates that originate from the database. In cases where the database cannot create a handle for a certificate, `None` will be returned. This handle should be stable across various instances of the application, and between applications. If a certificate is modified in the database, then it is not guaranteed that this handle will continue to point to it. ## `certificate` certificate for which to create a handle. # Returns a newly allocated string containing the handle. Lookup a certificate by its handle. The handle should have been created by calling `TlsDatabaseExt::create_certificate_handle` on a `TlsDatabase` object of the same TLS backend. The handle is designed to remain valid across instantiations of the database. If the handle is no longer valid, or does not point to a certificate in this database, then `None` will be returned. This function can block, use `TlsDatabaseExt::lookup_certificate_for_handle_async` to perform the lookup operation asynchronously. ## `handle` a certificate handle ## `interaction` used to interact with the user if necessary ## `flags` Flags which affect the lookup. ## `cancellable` a `Cancellable`, or `None` # Returns a newly allocated `TlsCertificate`, or `None`. Use `gobject::ObjectExt::unref` to release the certificate. Asynchronously lookup a certificate by its handle in the database. See `TlsDatabaseExt::lookup_certificate_for_handle` for more information. ## `handle` a certificate handle ## `interaction` used to interact with the user if necessary ## `flags` Flags which affect the lookup. ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call when the operation completes ## `user_data` the data to pass to the callback function Finish an asynchronous lookup of a certificate by its handle. See `g_tls_database_lookup_certificate_by_handle` for more information. If the handle is no longer valid, or does not point to a certificate in this database, then `None` will be returned. ## `result` a `AsyncResult`. # Returns a newly allocated `TlsCertificate` object. Use `gobject::ObjectExt::unref` to release the certificate. Lookup the issuer of `certificate` in the database. The `issuer` property of `certificate` is not modified, and the two certificates are not hooked into a chain. This function can block, use `TlsDatabaseExt::lookup_certificate_issuer_async` to perform the lookup operation asynchronously. ## `certificate` a `TlsCertificate` ## `interaction` used to interact with the user if necessary ## `flags` flags which affect the lookup operation ## `cancellable` a `Cancellable`, or `None` # Returns a newly allocated issuer `TlsCertificate`, or `None`. Use `gobject::ObjectExt::unref` to release the certificate. Asynchronously lookup the issuer of `certificate` in the database. See `TlsDatabaseExt::lookup_certificate_issuer` for more information. ## `certificate` a `TlsCertificate` ## `interaction` used to interact with the user if necessary ## `flags` flags which affect the lookup operation ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call when the operation completes ## `user_data` the data to pass to the callback function Finish an asynchronous lookup issuer operation. See `TlsDatabaseExt::lookup_certificate_issuer` for more information. ## `result` a `AsyncResult`. # Returns a newly allocated issuer `TlsCertificate`, or `None`. Use `gobject::ObjectExt::unref` to release the certificate. Lookup certificates issued by this issuer in the database. This function can block, use `TlsDatabaseExt::lookup_certificates_issued_by_async` to perform the lookup operation asynchronously. ## `issuer_raw_dn` a `glib::ByteArray` which holds the DER encoded issuer DN. ## `interaction` used to interact with the user if necessary ## `flags` Flags which affect the lookup operation. ## `cancellable` a `Cancellable`, or `None` # Returns a newly allocated list of `TlsCertificate` objects. Use `gobject::ObjectExt::unref` on each certificate, and `glib::List::free` on the release the list. Asynchronously lookup certificates issued by this issuer in the database. See `TlsDatabaseExt::lookup_certificates_issued_by` for more information. The database may choose to hold a reference to the issuer byte array for the duration of of this asynchronous operation. The byte array should not be modified during this time. ## `issuer_raw_dn` a `glib::ByteArray` which holds the DER encoded issuer DN. ## `interaction` used to interact with the user if necessary ## `flags` Flags which affect the lookup operation. ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call when the operation completes ## `user_data` the data to pass to the callback function Finish an asynchronous lookup of certificates. See `TlsDatabaseExt::lookup_certificates_issued_by` for more information. ## `result` a `AsyncResult`. # Returns a newly allocated list of `TlsCertificate` objects. Use `gobject::ObjectExt::unref` on each certificate, and `glib::List::free` on the release the list. Determines the validity of a certificate chain after looking up and adding any missing certificates to the chain. `chain` is a chain of `TlsCertificate` objects each pointing to the next certificate in the chain by its `TlsCertificate:issuer` property. The chain may initially consist of one or more certificates. After the verification process is complete, `chain` may be modified by adding missing certificates, or removing extra certificates. If a certificate anchor was found, then it is added to the `chain`. `purpose` describes the purpose (or usage) for which the certificate is being used. Typically `purpose` will be set to `G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER` which means that the certificate is being used to authenticate a server (and we are acting as the client). The `identity` is used to check for pinned certificates (trust exceptions) in the database. These will override the normal verification process on a host by host basis. Currently there are no `flags`, and `TlsDatabaseVerifyFlags::None` should be used. If `chain` is found to be valid, then the return value will be 0. If `chain` is found to be invalid, then the return value will indicate the problems found. If the function is unable to determine whether `chain` is valid or not (eg, because `cancellable` is triggered before it completes) then the return value will be `TlsCertificateFlags::GenericError` and `error` will be set accordingly. `error` is not set when `chain` is successfully analyzed but found to be invalid. This function can block, use `TlsDatabaseExt::verify_chain_async` to perform the verification operation asynchronously. ## `chain` a `TlsCertificate` chain ## `purpose` the purpose that this certificate chain will be used for. ## `identity` the expected peer identity ## `interaction` used to interact with the user if necessary ## `flags` additional verify flags ## `cancellable` a `Cancellable`, or `None` # Returns the appropriate `TlsCertificateFlags` which represents the result of verification. Asynchronously determines the validity of a certificate chain after looking up and adding any missing certificates to the chain. See `TlsDatabaseExt::verify_chain` for more information. ## `chain` a `TlsCertificate` chain ## `purpose` the purpose that this certificate chain will be used for. ## `identity` the expected peer identity ## `interaction` used to interact with the user if necessary ## `flags` additional verify flags ## `cancellable` a `Cancellable`, or `None` ## `callback` callback to call when the operation completes ## `user_data` the data to pass to the callback function Finish an asynchronous verify chain operation. See `TlsDatabaseExt::verify_chain` for more information. If `chain` is found to be valid, then the return value will be 0. If `chain` is found to be invalid, then the return value will indicate the problems found. If the function is unable to determine whether `chain` is valid or not (eg, because `cancellable` is triggered before it completes) then the return value will be `TlsCertificateFlags::GenericError` and `error` will be set accordingly. `error` is not set when `chain` is successfully analyzed but found to be invalid. ## `result` a `AsyncResult`. # Returns the appropriate `TlsCertificateFlags` which represents the result of verification. Flags for `TlsDatabaseExt::lookup_certificate_for_handle`, `TlsDatabaseExt::lookup_certificate_issuer`, and `TlsDatabaseExt::lookup_certificates_issued_by`. No lookup flags Restrict lookup to certificates that have a private key. `TlsFileDatabase` is implemented by `TlsDatabase` objects which load their certificate information from a file. It is an interface which TLS library specific subtypes implement. # Implements [`TlsFileDatabaseExt`](trait.TlsFileDatabaseExt.html), [`TlsDatabaseExt`](trait.TlsDatabaseExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TlsFileDatabase` methods. # Implementors [`TlsFileDatabase`](struct.TlsFileDatabase.html) Creates a new `TlsFileDatabase` which uses anchor certificate authorities in `anchors` to verify certificate chains. The certificates in `anchors` must be PEM encoded. ## `anchors` filename of anchor certificate authorities. # Returns the new `TlsFileDatabase`, or `None` on error The path to a file containing PEM encoded certificate authority root anchors. The certificates in this file will be treated as root authorities for the purpose of verifying other certificates via the `TlsDatabaseExt::verify_chain` operation. The path to a file containing PEM encoded certificate authority root anchors. The certificates in this file will be treated as root authorities for the purpose of verifying other certificates via the `TlsDatabaseExt::verify_chain` operation. `TlsInteraction` provides a mechanism for the TLS connection and database code to interact with the user. It can be used to ask the user for passwords. To use a `TlsInteraction` with a TLS connection use `TlsConnectionExt::set_interaction`. Callers should instantiate a derived class that implements the various interaction methods to show the required dialogs. Callers should use the 'invoke' functions like `TlsInteractionExt::invoke_ask_password` to run interaction methods. These functions make sure that the interaction is invoked in the main loop and not in the current thread, if the current thread is not running the main loop. Derived classes can choose to implement whichever interactions methods they'd like to support by overriding those virtual methods in their class initialization function. Any interactions not implemented will return `TlsInteractionResult::Unhandled`. If a derived class implements an async method, it must also implement the corresponding finish method. # Implements [`TlsInteractionExt`](trait.TlsInteractionExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TlsInteraction` methods. # Implementors [`TlsInteraction`](struct.TlsInteraction.html) Run synchronous interaction to ask the user for a password. In general, `TlsInteractionExt::invoke_ask_password` should be used instead of this function. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The `password` value will be filled in and then `callback` will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. If the interaction is cancelled by the cancellation object, or by the user then `TlsInteractionResult::Failed` will be returned with an error that contains a `IOErrorEnum::Cancelled` error code. Certain implementations may not support immediate cancellation. ## `password` a `TlsPassword` object ## `cancellable` an optional `Cancellable` cancellation object # Returns The status of the ask password interaction. Run asynchronous interaction to ask the user for a password. In general, `TlsInteractionExt::invoke_ask_password` should be used instead of this function. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The `password` value will be filled in and then `callback` will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. If the interaction is cancelled by the cancellation object, or by the user then `TlsInteractionResult::Failed` will be returned with an error that contains a `IOErrorEnum::Cancelled` error code. Certain implementations may not support immediate cancellation. Certain implementations may not support immediate cancellation. ## `password` a `TlsPassword` object ## `cancellable` an optional `Cancellable` cancellation object ## `callback` will be called when the interaction completes ## `user_data` data to pass to the `callback` Complete an ask password user interaction request. This should be once the `TlsInteractionExt::ask_password_async` completion callback is called. If `TlsInteractionResult::Handled` is returned, then the `TlsPassword` passed to `TlsInteractionExt::ask_password` will have its password filled in. If the interaction is cancelled by the cancellation object, or by the user then `TlsInteractionResult::Failed` will be returned with an error that contains a `IOErrorEnum::Cancelled` error code. ## `result` the result passed to the callback # Returns The status of the ask password interaction. Invoke the interaction to ask the user for a password. It invokes this interaction in the main loop, specifically the `glib::MainContext` returned by `glib::MainContext::get_thread_default` when the interaction is created. This is called by called by `TlsConnection` or `TlsDatabase` to ask the user for a password. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The `password` value will be filled in and then `callback` will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. The implementation can either be a synchronous (eg: modal dialog) or an asynchronous one (eg: modeless dialog). This function will take care of calling which ever one correctly. If the interaction is cancelled by the cancellation object, or by the user then `TlsInteractionResult::Failed` will be returned with an error that contains a `IOErrorEnum::Cancelled` error code. Certain implementations may not support immediate cancellation. ## `password` a `TlsPassword` object ## `cancellable` an optional `Cancellable` cancellation object # Returns The status of the ask password interaction. Invoke the interaction to ask the user to choose a certificate to use with the connection. It invokes this interaction in the main loop, specifically the `glib::MainContext` returned by `glib::MainContext::get_thread_default` when the interaction is created. This is called by called by `TlsConnection` when the peer requests a certificate during the handshake. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which may or may not abort the TLS connection. The implementation can either be a synchronous (eg: modal dialog) or an asynchronous one (eg: modeless dialog). This function will take care of calling which ever one correctly. If the interaction is cancelled by the cancellation object, or by the user then `TlsInteractionResult::Failed` will be returned with an error that contains a `IOErrorEnum::Cancelled` error code. Certain implementations may not support immediate cancellation. ## `connection` a `TlsConnection` object ## `flags` flags providing more information about the request ## `cancellable` an optional `Cancellable` cancellation object # Returns The status of the certificate request interaction. Run synchronous interaction to ask the user to choose a certificate to use with the connection. In general, `TlsInteractionExt::invoke_request_certificate` should be used instead of this function. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. If `TlsInteractionResult::Handled` is returned, then the `TlsConnection` passed to `TlsInteractionExt::request_certificate` will have had its `TlsConnection:certificate` filled in. If the interaction is cancelled by the cancellation object, or by the user then `TlsInteractionResult::Failed` will be returned with an error that contains a `IOErrorEnum::Cancelled` error code. Certain implementations may not support immediate cancellation. ## `connection` a `TlsConnection` object ## `flags` flags providing more information about the request ## `cancellable` an optional `Cancellable` cancellation object # Returns The status of the request certificate interaction. Run asynchronous interaction to ask the user for a certificate to use with the connection. In general, `TlsInteractionExt::invoke_request_certificate` should be used instead of this function. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. `callback` will be called when the operation completes. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. ## `connection` a `TlsConnection` object ## `flags` flags providing more information about the request ## `cancellable` an optional `Cancellable` cancellation object ## `callback` will be called when the interaction completes ## `user_data` data to pass to the `callback` Complete an request certificate user interaction request. This should be once the `TlsInteractionExt::request_certificate_async` completion callback is called. If `TlsInteractionResult::Handled` is returned, then the `TlsConnection` passed to `TlsInteractionExt::request_certificate_async` will have had its `TlsConnection:certificate` filled in. If the interaction is cancelled by the cancellation object, or by the user then `TlsInteractionResult::Failed` will be returned with an error that contains a `IOErrorEnum::Cancelled` error code. ## `result` the result passed to the callback # Returns The status of the request certificate interaction. `TlsInteractionResult` is returned by various functions in `TlsInteraction` when finishing an interaction request. The interaction was unhandled (i.e. not implemented). The interaction completed, and resulting data is available. The interaction has failed, or was cancelled. and the operation should be aborted. Holds a password used in TLS. # Implements [`TlsPasswordExt`](trait.TlsPasswordExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TlsPassword` methods. # Implementors [`TlsPassword`](struct.TlsPassword.html) Create a new `TlsPassword` object. ## `flags` the password flags ## `description` description of what the password is for # Returns The newly allocated password object Get a description string about what the password will be used for. # Returns The description of the password. Get flags about the password. # Returns The flags about the password. Get the password value. If `length` is not `None` then it will be filled in with the length of the password value. (Note that the password value is not nul-terminated, so you can only pass `None` for `length` in contexts where you know the password will have a certain fixed length.) ## `length` location to place the length of the password. # Returns The password value (owned by the password object). Get a user readable translated warning. Usually this warning is a representation of the password flags returned from `TlsPasswordExt::get_flags`. # Returns The warning. Set a description string about what the password will be used for. ## `description` The description of the password Set flags about the password. ## `flags` The flags about the password Set the value for this password. The `value` will be copied by the password object. Specify the `length`, for a non-nul-terminated password. Pass -1 as `length` if using a nul-terminated password, and `length` will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.) ## `value` the new password value ## `length` the length of the password, or -1 Provide the value for this password. The `value` will be owned by the password object, and later freed using the `destroy` function callback. Specify the `length`, for a non-nul-terminated password. Pass -1 as `length` if using a nul-terminated password, and `length` will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.) ## `value` the value for the password ## `length` the length of the password, or -1 ## `destroy` a function to use to free the password. Set a user readable translated warning. Usually this warning is a representation of the password flags returned from `TlsPasswordExt::get_flags`. ## `warning` The user readable warning When to allow rehandshaking. See `TlsConnectionExt::set_rehandshake_mode`. Never allow rehandshaking Allow safe rehandshaking only Allow unsafe rehandshaking `TlsServerConnection` is the server-side subclass of `TlsConnection`, representing a server-side TLS connection. # Implements [`TlsServerConnectionExt`](trait.TlsServerConnectionExt.html), [`TlsConnectionExt`](trait.TlsConnectionExt.html), [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `TlsServerConnection` methods. # Implementors [`TlsServerConnection`](struct.TlsServerConnection.html) Creates a new `TlsServerConnection` wrapping `base_io_stream` (which must have pollable input and output streams). See the documentation for `TlsConnection:base-io-stream` for restrictions on when application code can run operations on the `base_io_stream` after this function has returned. ## `base_io_stream` the `IOStream` to wrap ## `certificate` the default server certificate, or `None` # Returns the new `TlsServerConnection`, or `None` on error The `TlsAuthenticationMode` for the server. This can be changed before calling `TlsConnectionExt::handshake` if you want to rehandshake with a different mode from the initial handshake. The `TlsAuthenticationMode` for the server. This can be changed before calling `TlsConnectionExt::handshake` if you want to rehandshake with a different mode from the initial handshake. `UnixInputStream` implements `InputStream` for reading from a UNIX file descriptor, including asynchronous operations. (If the file descriptor refers to a socket or pipe, this will use `poll` to do asynchronous I/O. If it refers to a regular file, it will fall back to doing asynchronous I/O in another thread.) Note that `` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file when using it. # Implements [`UnixInputStreamExt`](trait.UnixInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableInputStreamExt`](trait.PollableInputStreamExt.html), [`UnixInputStreamExtManual`](prelude/trait.UnixInputStreamExtManual.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html), [`PollableInputStreamExtManual`](prelude/trait.PollableInputStreamExtManual.html) Trait containing all `UnixInputStream` methods. # Implementors [`UnixInputStream`](struct.UnixInputStream.html) Creates a new `UnixInputStream` for the given `fd`. If `close_fd` is `true`, the file descriptor will be closed when the stream is closed. ## `fd` a UNIX file descriptor ## `close_fd` `true` to close the file descriptor when done # Returns a new `UnixInputStream` Returns whether the file descriptor of `self` will be closed when the stream is closed. # Returns `true` if the file descriptor is closed when done Return the UNIX file descriptor that the stream reads from. # Returns The file descriptor of `self` Sets whether the file descriptor of `self` shall be closed when the stream is closed. ## `close_fd` `true` to close the file descriptor when done Whether to close the file descriptor when the stream is closed. Whether to close the file descriptor when the stream is closed. The file descriptor that the stream reads from. The file descriptor that the stream reads from. `UnixOutputStream` implements `OutputStream` for writing to a UNIX file descriptor, including asynchronous operations. (If the file descriptor refers to a socket or pipe, this will use `poll` to do asynchronous I/O. If it refers to a regular file, it will fall back to doing asynchronous I/O in another thread.) Note that `` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file when using it. # Implements [`UnixOutputStreamExt`](trait.UnixOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableOutputStreamExt`](trait.PollableOutputStreamExt.html), [`UnixOutputStreamExtManual`](prelude/trait.UnixOutputStreamExtManual.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html), [`PollableOutputStreamExtManual`](prelude/trait.PollableOutputStreamExtManual.html) Trait containing all `UnixOutputStream` methods. # Implementors [`UnixOutputStream`](struct.UnixOutputStream.html) Creates a new `UnixOutputStream` for the given `fd`. If `close_fd`, is `true`, the file descriptor will be closed when the output stream is destroyed. ## `fd` a UNIX file descriptor ## `close_fd` `true` to close the file descriptor when done # Returns a new `OutputStream` Returns whether the file descriptor of `self` will be closed when the stream is closed. # Returns `true` if the file descriptor is closed when done Return the UNIX file descriptor that the stream writes to. # Returns The file descriptor of `self` Sets whether the file descriptor of `self` shall be closed when the stream is closed. ## `close_fd` `true` to close the file descriptor when done Whether to close the file descriptor when the stream is closed. Whether to close the file descriptor when the stream is closed. The file descriptor that the stream writes to. The file descriptor that the stream writes to. Support for UNIX-domain (also known as local) sockets. UNIX domain sockets are generally visible in the filesystem. However, some systems support abstract socket names which are not visible in the filesystem and not affected by the filesystem permissions, visibility, etc. Currently this is only supported under Linux. If you attempt to use abstract sockets on other systems, function calls may return `IOErrorEnum::NotSupported` errors. You can use `UnixSocketAddress::abstract_names_supported` to see if abstract names are supported. Note that `` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file when using it. # Implements [`UnixSocketAddressExt`](trait.UnixSocketAddressExt.html), [`SocketAddressExt`](trait.SocketAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html), [`UnixSocketAddressExtManual`](prelude/trait.UnixSocketAddressExtManual.html) Trait containing all `UnixSocketAddress` methods. # Implementors [`UnixSocketAddress`](struct.UnixSocketAddress.html) Creates a new `UnixSocketAddress` for `path`. To create abstract socket addresses, on systems that support that, use `UnixSocketAddress::new_abstract`. ## `path` the socket path # Returns a new `UnixSocketAddress` Creates a new `UnixSocketAddressType::AbstractPadded` `UnixSocketAddress` for `path`. # Deprecated Use `UnixSocketAddress::new_with_type`. ## `path` the abstract name ## `path_len` the length of `path`, or -1 # Returns a new `UnixSocketAddress` Creates a new `UnixSocketAddress` of type `type_` with name `path`. If `type_` is `UnixSocketAddressType::Path`, this is equivalent to calling `UnixSocketAddress::new`. If `type_` is `UnixSocketAddressType::Anonymous`, `path` and `path_len` will be ignored. If `path_type` is `UnixSocketAddressType::Abstract`, then `path_len` bytes of `path` will be copied to the socket's path, and only those bytes will be considered part of the name. (If `path_len` is -1, then `path` is assumed to be NUL-terminated.) For example, if `path` was "test", then calling `SocketAddressExt::get_native_size` on the returned socket would return 7 (2 bytes of overhead, 1 byte for the abstract-socket indicator byte, and 4 bytes for the name "test"). If `path_type` is `UnixSocketAddressType::AbstractPadded`, then `path_len` bytes of `path` will be copied to the socket's path, the rest of the path will be padded with 0 bytes, and the entire zero-padded buffer will be considered the name. (As above, if `path_len` is -1, then `path` is assumed to be NUL-terminated.) In this case, `SocketAddressExt::get_native_size` will always return the full size of a `struct sockaddr_un`, although `UnixSocketAddressExt::get_path_len` will still return just the length of `path`. `UnixSocketAddressType::Abstract` is preferred over `UnixSocketAddressType::AbstractPadded` for new programs. Of course, when connecting to a server created by another process, you must use the appropriate type corresponding to how that process created its listening socket. ## `path` the name ## `path_len` the length of `path`, or -1 ## `type_` a `UnixSocketAddressType` # Returns a new `UnixSocketAddress` Checks if abstract UNIX domain socket names are supported. # Returns `true` if supported, `false` otherwise Gets `self`'s type. # Returns a `UnixSocketAddressType` Tests if `self` is abstract. # Deprecated Use `UnixSocketAddressExt::get_address_type` # Returns `true` if the address is abstract, `false` otherwise Gets `self`'s path, or for abstract sockets the "name". Guaranteed to be zero-terminated, but an abstract socket may contain embedded zeros, and thus you should use `UnixSocketAddressExt::get_path_len` to get the true length of this string. # Returns the path for `self` Gets the length of `self`'s path. For details, see `UnixSocketAddress::get_path`. # Returns the length of the path Whether or not this is an abstract address # Deprecated Use `UnixSocketAddress:address-type`, which distinguishes between zero-padded and non-zero-padded abstract addresses. Whether or not this is an abstract address # Deprecated Use `UnixSocketAddress:address-type`, which distinguishes between zero-padded and non-zero-padded abstract addresses. The type of name used by a `UnixSocketAddress`. `UnixSocketAddressType::Path` indicates a traditional unix domain socket bound to a filesystem path. `UnixSocketAddressType::Anonymous` indicates a socket not bound to any name (eg, a client-side socket, or a socket created with `socketpair`). For abstract sockets, there are two incompatible ways of naming them; the man pages suggest using the entire `struct sockaddr_un` as the name, padding the unused parts of the `sun_path` field with zeroes; this corresponds to `UnixSocketAddressType::AbstractPadded`. However, many programs instead just use a portion of `sun_path`, and pass an appropriate smaller length to `bind` or `connect`. This is `UnixSocketAddressType::Abstract`. invalid anonymous a filesystem path an abstract name an abstract name, 0-padded to the full length of a unix socket name Entry point for using GIO functionality. # Implements [`VfsExt`](trait.VfsExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Vfs` methods. # Implementors [`Vfs`](struct.Vfs.html) Gets the default `Vfs` for the system. # Returns a `Vfs`. Gets the local `Vfs` for the system. # Returns a `Vfs`. Gets a `File` for `path`. ## `path` a string containing a VFS path. # Returns a `File`. Free the returned object with `gobject::ObjectExt::unref`. Gets a `File` for `uri`. This operation never fails, but the returned object might not support any I/O operation if the URI is malformed or if the URI scheme is not supported. ## `uri` a string containing a URI # Returns a `File`. Free the returned object with `gobject::ObjectExt::unref`. Gets a list of URI schemes supported by `self`. # Returns a `None`-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. Checks if the VFS is active. # Returns `true` if construction of the `self` was successful and it is now active. This operation never fails, but the returned object might not support any I/O operations if the `parse_name` cannot be parsed by the `Vfs` module. ## `parse_name` a string to be parsed by the VFS module. # Returns a `File` for the given `parse_name`. Free the returned object with `gobject::ObjectExt::unref`. Registers `uri_func` and `parse_name_func` as the `File` URI and parse name lookup functions for URIs with a scheme matching `scheme`. Note that `scheme` is registered only within the running application, as opposed to desktop-wide as it happens with GVfs backends. When a `File` is requested with an URI containing `scheme` (e.g. through `File::new_for_uri`), `uri_func` will be called to allow a custom constructor. The implementation of `uri_func` should not be blocking, and must not call `VfsExt::register_uri_scheme` or `VfsExt::unregister_uri_scheme`. When `File::parse_name` is called with a parse name obtained from such file, `parse_name_func` will be called to allow the `File` to be created again. In that case, it's responsibility of `parse_name_func` to make sure the parse name matches what the custom `File` implementation returned when `File::get_parse_name` was previously called. The implementation of `parse_name_func` should not be blocking, and must not call `VfsExt::register_uri_scheme` or `VfsExt::unregister_uri_scheme`. It's an error to call this function twice with the same scheme. To unregister a custom URI scheme, use `VfsExt::unregister_uri_scheme`. Feature: `v2_50` ## `scheme` an URI scheme, e.g. "http" ## `uri_func` a `GVfsFileLookupFunc` ## `uri_data` custom data passed to be passed to `uri_func`, or `None` ## `uri_destroy` function to be called when unregistering the URI scheme, or when `self` is disposed, to free the resources used by the URI lookup function ## `parse_name_func` a `GVfsFileLookupFunc` ## `parse_name_data` custom data passed to be passed to `parse_name_func`, or `None` ## `parse_name_destroy` function to be called when unregistering the URI scheme, or when `self` is disposed, to free the resources used by the parse name lookup function # Returns `true` if `scheme` was successfully registered, or `false` if a handler for `scheme` already exists. Unregisters the URI handler for `scheme` previously registered with `VfsExt::register_uri_scheme`. Feature: `v2_50` ## `scheme` an URI scheme, e.g. "http" # Returns `true` if `scheme` was successfully unregistered, or `false` if a handler for `scheme` does not exist. The `Volume` interface represents user-visible objects that can be mounted. Note, when porting from GnomeVFS, `Volume` is the moral equivalent of `GnomeVFSDrive`. Mounting a `Volume` instance is an asynchronous operation. For more information about asynchronous operations, see `AsyncResult` and `Task`. To mount a `Volume`, first call `Volume::mount` with (at least) the `Volume` instance, optionally a `MountOperation` object and a `GAsyncReadyCallback`. Typically, one will only want to pass `None` for the `MountOperation` if automounting all volumes when a desktop session starts since it's not desirable to put up a lot of dialogs asking for credentials. The callback will be fired when the operation has resolved (either with success or failure), and a `GAsyncReady` structure will be passed to the callback. That callback should then call `Volume::mount_finish` with the `Volume` instance and the `GAsyncReady` data to see if the operation was completed successfully. If an `error` is present when `Volume::mount_finish` is called, then it will be filled with any error information. ## Volume Identifiers # {`volume`-identifier} It is sometimes necessary to directly access the underlying operating system object behind a volume (e.g. for passing a volume to an application via the commandline). For this purpose, GIO allows to obtain an 'identifier' for the volume. There can be different kinds of identifiers, such as Hal UDIs, filesystem labels, traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined strings as names for the different kinds of identifiers: `G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc. Use `Volume::get_identifier` to obtain an identifier for a volume. Note that `G_VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available when the gvfs hal volume monitor is in use. Other volume monitors will generally be able to provide the `G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE` identifier, which can be used to obtain a hal device by means of `libhal_manager_find_device_string_match`. # Implements [`VolumeExt`](trait.VolumeExt.html) Trait containing all `Volume` methods. # Implementors [`Volume`](struct.Volume.html) Checks if a volume can be ejected. # Returns `true` if the `self` can be ejected. `false` otherwise Checks if a volume can be mounted. # Returns `true` if the `self` can be mounted. `false` otherwise Ejects a volume. This is an asynchronous operation, and is finished by calling `Volume::eject_with_operation_finish` with the `self` and `AsyncResult` data returned in the `callback`. ## `flags` flags affecting the unmount if required for eject ## `mount_operation` a `MountOperation` or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback`, or `None` ## `user_data` user data passed to `callback` Finishes ejecting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. ## `result` a `AsyncResult` # Returns `true` if the volume was successfully ejected. `false` otherwise Gets the kinds of [identifiers][volume-identifier] that `self` has. Use `Volume::get_identifier` to obtain the identifiers themselves. # Returns a `None`-terminated array of strings containing kinds of identifiers. Use `g_strfreev` to free. Gets the activation root for a `Volume` if it is known ahead of mount time. Returns `None` otherwise. If not `None` and if `self` is mounted, then the result of `Mount::get_root` on the `Mount` object obtained from `Volume::get_mount` will always either be equal or a prefix of what this function returns. In other words, in code ```C GMount *mount; GFile *mount_root GFile *volume_activation_root; mount = g_volume_get_mount (volume); // mounted, so never NULL mount_root = g_mount_get_root (mount); volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL ``` then the expression ```C (g_file_has_prefix (volume_activation_root, mount_root) || g_file_equal (volume_activation_root, mount_root)) ``` will always be `true`. Activation roots are typically used in `VolumeMonitor` implementations to find the underlying mount to shadow, see `Mount::is_shadowed` for more details. # Returns the activation root of `self` or `None`. Use `gobject::ObjectExt::unref` to free. Gets the drive for the `self`. # Returns a `Drive` or `None` if `self` is not associated with a drive. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the icon for `self`. # Returns a `Icon`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the identifier of the given kind for `self`. See the [introduction][volume-identifier] for more information about volume identifiers. ## `kind` the kind of identifier to return # Returns a newly allocated string containing the requested identifier, or `None` if the `Volume` doesn't have this kind of identifier Gets the mount for the `self`. # Returns a `Mount` or `None` if `self` isn't mounted. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the name of `self`. # Returns the name for the given `self`. The returned string should be freed with `g_free` when no longer needed. Gets the sort key for `self`, if any. # Returns Sorting key for `self` or `None` if no such key is available Gets the symbolic icon for `self`. # Returns a `Icon`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the UUID for the `self`. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns `None` if there is no UUID available. # Returns the UUID for `self` or `None` if no UUID can be computed. The returned string should be freed with `g_free` when no longer needed. Mounts a volume. This is an asynchronous operation, and is finished by calling `Volume::mount_finish` with the `self` and `AsyncResult` returned in the `callback`. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation` or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback`, or `None` ## `user_data` user data that gets passed to `callback` Finishes mounting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. If the mount operation succeeded, `Volume::get_mount` on `self` is guaranteed to return the mount right after calling this function; there's no need to listen for the 'mount-added' signal on `VolumeMonitor`. ## `result` a `AsyncResult` # Returns `true`, `false` if operation failed Returns whether the volume should be automatically mounted. # Returns `true` if the volume should be automatically mounted Emitted when the volume has been changed. This signal is emitted when the `Volume` have been removed. If the recipient is holding references to the object they should release them so the object can be finalized. `VolumeMonitor` is for listing the user interesting devices and volumes on the computer. In other words, what a file selector or file manager would show in a sidebar. `VolumeMonitor` is not [thread-default-context aware][g-main-context-push-thread-default], and so should not be used other than from the main thread, with no thread-default-context active. # Implements [`VolumeMonitorExt`](trait.VolumeMonitorExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `VolumeMonitor` methods. # Implementors [`VolumeMonitor`](struct.VolumeMonitor.html) Gets the volume monitor used by gio. # Returns a reference to the `VolumeMonitor` used by gio. Call `gobject::ObjectExt::unref` when done with it. Gets a list of drives connected to the system. The returned list should be freed with `glib::List::free`, after its elements have been unreffed with `gobject::ObjectExt::unref`. # Returns a `glib::List` of connected `Drive` objects. Finds a `Mount` object by its UUID (see `Mount::get_uuid`) ## `uuid` the UUID to look for # Returns a `Mount` or `None` if no such mount is available. Free the returned object with `gobject::ObjectExt::unref`. Gets a list of the mounts on the system. The returned list should be freed with `glib::List::free`, after its elements have been unreffed with `gobject::ObjectExt::unref`. # Returns a `glib::List` of `Mount` objects. Finds a `Volume` object by its UUID (see `Volume::get_uuid`) ## `uuid` the UUID to look for # Returns a `Volume` or `None` if no such volume is available. Free the returned object with `gobject::ObjectExt::unref`. Gets a list of the volumes on the system. The returned list should be freed with `glib::List::free`, after its elements have been unreffed with `gobject::ObjectExt::unref`. # Returns a `glib::List` of `Volume` objects. Emitted when a drive changes. ## `drive` the drive that changed Emitted when a drive is connected to the system. ## `drive` a `Drive` that was connected. Emitted when a drive is disconnected from the system. ## `drive` a `Drive` that was disconnected. Emitted when the eject button is pressed on `drive`. ## `drive` the drive where the eject button was pressed Emitted when the stop button is pressed on `drive`. ## `drive` the drive where the stop button was pressed Emitted when a mount is added. ## `mount` a `Mount` that was added. Emitted when a mount changes. ## `mount` a `Mount` that changed. May be emitted when a mount is about to be removed. This signal depends on the backend and is only emitted if GIO was used to unmount. ## `mount` a `Mount` that is being unmounted. Emitted when a mount is removed. ## `mount` a `Mount` that was removed. Emitted when a mountable volume is added to the system. ## `volume` a `Volume` that was added. Emitted when mountable volume is changed. ## `volume` a `Volume` that changed. Emitted when a mountable volume is removed from the system. ## `volume` a `Volume` that was removed. Zlib decompression # Implements [`ZlibCompressorExt`](trait.ZlibCompressorExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ConverterExt`](trait.ConverterExt.html), [`ConverterExtManual`](prelude/trait.ConverterExtManual.html) Trait containing all `ZlibCompressor` methods. # Implementors [`ZlibCompressor`](struct.ZlibCompressor.html) Creates a new `ZlibCompressor`. ## `format` The format to use for the compressed data ## `level` compression level (0-9), -1 for default # Returns a new `ZlibCompressor` Returns the `ZlibCompressor:file-info` property. # Returns a `FileInfo`, or `None` Sets `file_info` in `self`. If non-`None`, and `self`'s `ZlibCompressor:format` property is `ZlibCompressorFormat::Gzip`, it will be used to set the file name and modification time in the GZIP header of the compressed data. Note: it is an error to call this function while a compression is in progress; it may only be called immediately after creation of `self`, or after resetting it with `Converter::reset`. ## `file_info` a `FileInfo` If set to a non-`None` `FileInfo` object, and `ZlibCompressor:format` is `ZlibCompressorFormat::Gzip`, the compressor will write the file name and modification time from the file info to the GZIP header. If set to a non-`None` `FileInfo` object, and `ZlibCompressor:format` is `ZlibCompressorFormat::Gzip`, the compressor will write the file name and modification time from the file info to the GZIP header. Used to select the type of data format to use for `ZlibDecompressor` and `ZlibCompressor`. deflate compression with zlib header gzip file format deflate compression with no header Zlib decompression # Implements [`ZlibDecompressorExt`](trait.ZlibDecompressorExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ConverterExt`](trait.ConverterExt.html), [`ConverterExtManual`](prelude/trait.ConverterExtManual.html) Trait containing all `ZlibDecompressor` methods. # Implementors [`ZlibDecompressor`](struct.ZlibDecompressor.html) Creates a new `ZlibDecompressor`. ## `format` The format to use for the compressed data # Returns a new `ZlibDecompressor` Retrieves the `FileInfo` constructed from the GZIP header data of compressed data processed by `compressor`, or `None` if `self`'s `ZlibDecompressor:format` property is not `ZlibCompressorFormat::Gzip`, or the header data was not fully processed yet, or it not present in the data stream at all. # Returns a `FileInfo`, or `None` A `FileInfo` containing the information found in the GZIP header of the data stream processed, or `None` if the header was not yet fully processed, is not present at all, or the compressor's `ZlibDecompressor:format` property is not `ZlibCompressorFormat::Gzip`. gtk-rs-lgpl-docs-0.1.12/glib/docs.md010064400007650000024000001142501344544746500153150ustar0000000000000000 `IMPL` Boxed wrapper implementation. Wrapper implementations for Boxed types. See `glib_wrapper!`. Memory management functions for a boxed type. Makes a copy. Frees the object. Encapsulates memory management logic for boxed types. A shared immutable byte slice (the equivalent of `Rc<[u8]>`). `From` implementations that take references (e.g. `&[u8]`) copy the data. The `from_static` constructor avoids copying static data. ``` use glib::Bytes; let v = vec![1, 2, 3]; let b = Bytes::from(&v); assert_eq!(v, b); let s = b"xyz"; let b = Bytes::from_static(s); assert_eq!(&s[..], b); ``` Copies `data` into a new shared slice. Creates a view into static `data` without copying. Representation of an `enum` for dynamically, at runtime, querying the values of the enum and using them. Create a new `EnumClass` from a `Type`. Returns `None` if `type_` is not representing an enum. `Type` of the enum. Gets `EnumValue` by integer `value`, if existing. Returns `None` if the enum does not contain any value with `value`. Gets `EnumValue` by string name `name`, if existing. Returns `None` if the enum does not contain any value with name `name`. Gets `EnumValue` by string nick `nick`, if existing. Returns `None` if the enum does not contain any value with nick `nick`. Gets all `EnumValue` of this `EnumClass`. Converts integer `value` to a `Value`, if part of the enum. Converts string name `name` to a `Value`, if part of the enum. Converts string nick `nick` to a `Value`, if part of the enum. Representation of a single enum value of an `EnumClass`. Get integer value corresponding to the value. Get name corresponding to the value. Get nick corresponding to the value. Convert enum value to a `Value`. Convert enum value from a `Value`. Get `EnumClass` to which the enum value belongs. Representation of a `flags` for dynamically, at runtime, querying the values of the enum and using them Create a new `FlagsClass` from a `Type` Returns `None` if `type_` is not representing a flags type. `Type` of the flags. Gets `FlagsValue` by integer `value`, if existing. Returns `None` if the flags do not contain any value with `value`. Gets `FlagsValue` by string name `name`, if existing. Returns `None` if the flags do not contain any value with name `name`. Gets `FlagsValue` by string nick `nick`, if existing. Returns `None` if the flags do not contain any value with nick `nick`. Gets all `FlagsValue` of this `FlagsClass`. Converts integer `value` to a `Value`, if part of the flags. Converts string name `name` to a `Value`, if part of the flags. Converts string nick `nick` to a `Value`, if part of the flags. Checks if the flags corresponding to integer `f` is set in `value`. Checks if the flags corresponding to string name `name` is set in `value`. Checks if the flags corresponding to string nick `nick` is set in `value`. Sets flags value corresponding to integer `f` in `value`, if part of that flags. If the flag is already set, it will succeed without doing any changes. Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original value otherwise. Sets flags value corresponding to string name `name` in `value`, if part of that flags. If the flag is already set, it will succeed without doing any changes. Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original value otherwise. Sets flags value corresponding to string nick `nick` in `value`, if part of that flags. If the flag is already set, it will succeed without doing any changes. Returns `Ok(value)` with the flag set if successful, or `Err(value)` with the original value otherwise. Unsets flags value corresponding to integer `f` in `value`, if part of that flags. If the flag is already unset, it will succeed without doing any changes. Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original value otherwise. Unsets flags value corresponding to string name `name` in `value`, if part of that flags. If the flag is already unset, it will succeed without doing any changes. Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original value otherwise. Unsets flags value corresponding to string nick `nick` in `value`, if part of that flags. If the flag is already unset, it will succeed without doing any changes. Returns `Ok(value)` with the flag unset if successful, or `Err(value)` with the original value otherwise. Returns a new `FlagsBuilder` for conveniently setting/unsetting flags and building a `Value`. Returns a new `FlagsBuilder` for conveniently setting/unsetting flags and building a `Value`. The `Value` is initialized with `value`. Representation of a single flags value of a `FlagsClass`. Get integer value corresponding to the value. Get name corresponding to the value. Get nick corresponding to the value. Convert flags value to a `Value`. Convert flags values from a `Value`. This returns all flags that are set. Get `FlagsClass` to which the flags value belongs. Builder for conveniently setting/unsetting flags and returning a `Value`. Example for getting a flags property, unsetting some flags and setting the updated flags on the object again: ```ignore let flags = obj.get_property("flags").unwrap(); let flags_class = FlagsClass::new(flags.type_()).unwrap(); let flags = flags_class.builder_with_value(flags).unwrap() .unset_by_nick("some-flag") .unset_by_nick("some-other-flag") .build() .unwrap(); obj.set_property("flags", &flags).unwrap(); ``` If setting/unsetting any value fails, `build()` returns `None`. Sets flags corresponding to integer value `f`. Sets flags corresponding to string name `name`. Sets flags corresponding to string nick `nick`. Unsets flags corresponding to integer value `f`. Unsets flags corresponding to string name `name`. Unsets flags corresponding to string nick `nick`. Converts to the final `Value`, unless any previous setting/unsetting of flags failed. `Error` binding and helper trait. A generic error capable of representing various error domains (types). Creates an error with supplied error enum variant and message. Checks if the error domain matches `T`. Tries to convert to a specific error enum. Returns `Some` if the error belongs to the enum's error domain and `None` otherwise. # Examples ```ignore if let Some(file_error) = error.kind::() { match file_error { FileError::Exist => ... FileError::Isdir => ... ... } } ``` ```ignore match error { Some(FileError::Exist) => ... Some(FileError::Isdir) => ... ... } ``` `GLib` error domain. This trait is implemented by error enums that represent error domains (types). Returns the quark identifying the error domain. As returned from `g_some_error_quark`. Gets the integer representation of the variant. Tries to convert an integer code to an enum variant. By convention, the `Failed` variant, if present, is a catch-all, i.e. any unrecognized codes map to it. Generic error used for functions that fail without any further information # **glib**, **gobject** and **gio** bindings for Rust This library contains - bindings to some essential GLib, GObject, GIO types and APIs, - common building blocks used in both handmade and machine generated bindings to GTK+ and other GLib-based libraries. It is the foundation for higher level libraries with uniform Rusty (safe and strongly typed) APIs. It avoids exposing GLib-specific data types where possible and is not meant to provide comprehensive GLib bindings, which would often amount to duplicating the Rust Standard Library or other utility crates. The library is a work in progress: expect missing functionality and breaking changes. # Dynamic typing Most types in the GLib family have type identifiers ([`Type`](types/enum.Type.html)). Their corresponding Rust types implement the [`StaticType`](types/trait.StaticType.html) trait. Dynamically typed [`Value`](value/index.html) can carry values of any `T: StaticType`. [`Variant`](variant/index.html) can carry values of `T: StaticVariantType`. # Errors Errors are represented by [`Error`](error/struct.Error.html), which can carry values from various [error domains](error/trait.ErrorDomain.html#implementors) (such as [`FileError`](enum.FileError.html)). # Objects Each class and interface has a corresponding smart pointer struct representing an instance of that type (e.g. `Object` for `GObject`, `gtk::Widget` for `GtkWidget`). They are reference counted and feature interior mutability similarly to Rust's `Rc>` idiom. Consequently, cloning objects is cheap and their methods never require mutable borrows. Two smart pointers are equal iff they point to the same object. The root of the object hierarchy is [`Object`](object/struct.Object.html). Inheritance and subtyping is denoted with the [`IsA`](object/trait.IsA.html) marker trait. The [`Cast`](object/trait.Cast.html) trait enables upcasting and downcasting. Interfaces and non-leaf classes also have corresponding traits (e.g. `ObjectExt` and `gtk::WidgetExt`), which are blanketly implemented for all their subtypes. # Under the hood GLib-based libraries largely operate on pointers to various boxed or reference counted structures so the bindings have to implement corresponding smart pointers (wrappers), which encapsulate resource management and safety checks. Such wrappers are defined via the [`glib_wrapper!`](macro.glib_wrapper!.html) macro, which uses abstractions defined in the [`wrapper`](wrapper/index.html), [`boxed`](boxed/index.html), [`shared`](shared/index.html) and [`object`](object/index.html) modules. The [`translate`](translate/index.html) module defines and partly implements conversions between high level Rust types (including the aforementioned wrappers) and their FFI counterparts. `IMPL` Object wrapper implementation and `Object` binding. Upcasting and downcasting support. Provides conversions up and down the class hierarchy tree. Upcasts an object to a superclass or interface `T`. *NOTE*: This statically checks at compile-time if casting is possible. It is not always known at compile-time, whether a specific object implements an interface or not, in which case `upcast` would fail to compile. `dynamic_cast` can be used in these circumstances, which is checking the types at runtime. # Example ```ignore let button = gtk::Button::new(); let widget = button.upcast::(); ``` Tries to downcast to a subclass or interface implementor `T`. Returns `Ok(T)` if the object is an instance of `T` and `Err(self)` otherwise. *NOTE*: This statically checks at compile-time if casting is possible. It is not always known at compile-time, whether a specific object implements an interface or not, in which case `upcast` would fail to compile. `dynamic_cast` can be used in these circumstances, which is checking the types at runtime. # Example ```ignore let button = gtk::Button::new(); let widget = button.upcast::(); assert!(widget.downcast::().is_ok()); ``` Returns `true` if the object is an instance of (can be cast to) `T`. Tries to cast to an object of type `T`. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while `downcast` and `upcast` will do many checks at compile-time already. It is not always known at compile-time, whether a specific object implements an interface or not, and checking as to be performed at runtime. Returns `Ok(T)` if the object is an instance of `T` and `Err(self)` otherwise. # Example ```ignore let button = gtk::Button::new(); let widget = button.dynamic_cast::(); assert!(widget.is_ok); let widget = widget.unwrap(); assert!(widget.dynamic_cast::().is_ok()); ``` Declares the "is a" relationship. `Self` is said to implement `T`. For instance, since originally `GtkWidget` is a subclass of `GObject` and implements the `GtkBuildable` interface, `gtk::Widget` implements `IsA` and `IsA`. The trait can only be implemented if the appropriate `ToGlibPtr` implementations exist. `T` always implements `IsA`. Downcasts support. Checks if it's possible to downcast to `T`. Returns `true` if the instance implements `T` and `false` otherwise. Tries to downcast to `T`. Returns `Ok(T)` if the instance implements `T` and `Err(Self)` otherwise. Downcasts to `T` unconditionally. Panics if compiled with `debug_assertions` and the instance doesn't implement `T`. Wrapper implementations for Object types. See `glib_wrapper!`. Traits and essential types intended for blanket imports. `IMPL` Shared (reference counted) wrapper implementation. Wrapper implementations for shared types. See `glib_wrapper!`. Encapsulates memory management logic for shared types. `IMPL` Low level signal support. Whether to propagate the signal to the default handler. Don't inhibit default handlers without a reason, they're usually helpful. The id of a source that is returned by `idle_add` and `timeout_add`. A value of 0 is a good default as it is never a valid source ID. Continue calling the closure in the future iterations or drop it. This is the return type of `idle_add` and `timeout_add` closures. `Continue(true)` keeps the closure assigned, to be rerun when appropriate. `Continue(false)` disconnects and drops it. Unwinding propagation guard. Aborts the process if destroyed while panicking. Adds a closure to be called by the default main loop when it's idle. `func` will be called repeatedly until it returns `Continue(false)`. The default main loop almost always is the main loop of the main thread. Thus the closure is called on the main thread. Adds a closure to be called by the default main loop at regular intervals with millisecond granularity. `func` will be called repeatedly every `interval` milliseconds until it returns `Continue(false)`. Precise timing is not guaranteed, the timeout may be delayed by other events. Prefer `timeout_add_seconds` when millisecond precision is not necessary. The default main loop almost always is the main loop of the main thread. Thus the closure is called on the main thread. Adds a closure to be called by the default main loop at regular intervals with second granularity. `func` will be called repeatedly every `interval` seconds until it returns `Continue(false)`. Precise timing is not guaranteed, the timeout may be delayed by other events. The default main loop almost always is the main loop of the main thread. Thus the closure is called on the main thread. Adds a closure to be called by the main loop the returned `Source` is attached to when a child process exits. `func` will be called when `pid` exits Adds a closure to be called by the default main loop whenever a UNIX signal is raised. `func` will be called repeatedly every time `signum` is raised until it returns `Continue(false)`. The default main loop almost always is the main loop of the main thread. Thus the closure is called on the main thread. Removes the source with the given id `source_id` from the default main context. It is a programmer error to attempt to remove a non-existent source. Note: source id are reused. For historical reasons, the native function always returns true, so we ignore it here. The priority of sources Adds a closure to be called by the main loop the return `Source` is attached to when it's idle. `func` will be called repeatedly until it returns `Continue(false)`. Adds a closure to be called by the main loop the returned `Source` is attached to at regular intervals with millisecond granularity. `func` will be called repeatedly every `interval` milliseconds until it returns `Continue(false)`. Precise timing is not guaranteed, the timeout may be delayed by other events. Prefer `timeout_add_seconds` when millisecond precision is not necessary. Adds a closure to be called by the main loop the returned `Source` is attached to at regular intervals with second granularity. `func` will be called repeatedly every `interval` seconds until it returns `Continue(false)`. Precise timing is not guaranteed, the timeout may be delayed by other events. Adds a closure to be called by the main loop the returned `Source` is attached to when a child process exits. `func` will be called when `pid` exits Adds a closure to be called by the main loop the returned `Source` is attached to whenever a UNIX signal is raised. `func` will be called repeatedly every time `signum` is raised until it returns `Continue(false)`. Translation between GLib/GLib-based FFI types and their Rust counterparts. This module allows library bindings authors to decouple type translation logic and use unified idioms at FFI boundaries. It also implements translation of GLib core data types. `FromGlib`, `from_glib` and `ToGlib` translate simple types like `bool`. ```ignore pub fn set_accept_focus(&self, accept_focus: bool) { unsafe { glib_ffi::gdk_window_set_accept_focus(self.pointer, accept_focus.to_glib()) } } pub fn get_accept_focus(&self) -> bool { unsafe { from_glib(glib_ffi::gdk_window_get_accept_focus(self.pointer)) } } ``` `ToGlibPtr`, `FromGlibPtrNone`, `FromGlibPtrFull` and `FromGlibPtrBorrow` work on `gpointer`s and support different modes of ownership transfer. ```ignore fn get_title(&self) -> Option { unsafe { let title = glib_ffi::gtk_window_get_title(self.pointer); from_glib_none(title) } } ``` Letting the foreign library borrow pointers from the Rust side often requires having a temporary variable of an intermediate type (e.g. `CString`). A `Stash` contains the temporary storage and a pointer into it that is valid for the lifetime of the `Stash`. As the lifetime of the `Stash` returned from `to_glib_none` is at least the enclosing statement, you can avoid explicitly binding the stash in most cases and just take the pointer out of it: ```ignore pub fn set_icon_name(&self, name: &str) { unsafe { glib_ffi::gdk_window_set_icon_name(self.pointer, name.to_glib_none().0) } } ``` A pointer Overrides pointer mutability. Use when the C API should be specifying a const pointer but doesn't. A trait for creating an uninitialized value. Handy for receiving outparams. Returns an uninitialized value. Returns an uninitialized value. Returns `Some(val)` if the condition is true and `None` otherwise. Helper type that stores temporary values used for translation. `P` is the foreign type pointer and the first element of the tuple. `T` is the Rust type that is translated. The second element of the tuple is the temporary storage defined by the implementation of `ToGlibPtr

for T` Say you want to pass a `*mut GdkWindowAttr` to a foreign function. The `Stash` will own a `GdkWindowAttr` and a `CString` that `GdkWindowAttr::title` points into. ```ignore impl <'a> ToGlibPtr<'a, *mut glib_ffi::GdkWindowAttr> for WindowAttr { type Storage = (Box, Stash<'a, *const c_char, Option>); fn to_glib_none(&'a self) -> Stash<*mut glib_ffi::GdkWindowAttr, WindowAttr> { let title = self.title.to_glib_none(); let mut attrs = Box::new(glib_ffi::GdkWindowAttr { title: title.0, // .... }); Stash(&mut *attrs, (attrs, title)) } } ``` Translate a simple type. Provides the default pointer type to be used in some container conversions. It's `*mut c_char` for `String`, `*mut GtkButton` for `gtk::Button`, etc. Translate to a pointer. Transfer: none. The pointer in the `Stash` is only valid for the lifetime of the `Stash`. Transfer: container. We transfer the container ownership to the foreign library retaining the elements ownership. Transfer: full. We transfer the ownership to the foreign library. Translate to a pointer with a mutable borrow. Transfer: none. The pointer in the `Stash` is only valid for the lifetime of the `Stash`. Translate a simple type. Translate a simple type. Translate from a pointer type without taking ownership, transfer: none. Translate from a pointer type taking ownership, transfer: full. Translate from a pointer type by borrowing. Don't increase the refcount Translate from a pointer type, transfer: none. Translate from a pointer type, transfer: full (assume ownership). Translate from a pointer type, borrowing the pointer. Translate from a container. Transfer: none. `num` is the advised number of elements. Transfer: container. `num` is the advised number of elements. Transfer: full. `num` is the advised number of elements. Translate from a container of pointers. Transfer: none. Transfer: container. Transfer: full. Runtime type information. A GLib or GLib-based library type An invalid `Type` used as error return value in some functions The fundamental type corresponding to the unit type `()` The fundamental type corresponding to `i8` The fundamental type corresponding to `u8` The fundamental type corresponding to `bool` The fundamental type corresponding to `i32` The fundamental type corresponding to `u32` The fundamental type corresponding to C `long` The fundamental type corresponding to C `unsigned long` The fundamental type corresponding to `i64` The fundamental type corresponding to `u64` The fundamental type corresponding to `f32` The fundamental type corresponding to `f64` The fundamental type corresponding to `String` The fundamental type corresponding to a pointer The fundamental type of GVariant The fundamental type from which all interfaces are derived The fundamental type from which all enumeration types are derived The fundamental type from which all flags types are derived The fundamental type from which all boxed types are derived The fundamental type from which all `GParamSpec` types are derived The fundamental type from which all objects are derived A non-fundamental type identified by value of type `usize` Types that are supported by GLib dynamic typing. Returns the type identifier of `Self`. Same as [`get_prgname()`]. [`get_prgname()`]: fn.get_prgname.html Same as [`set_prgname()`]. [`set_prgname()`]: fn.set_prgname.html `Value` binding and helper traits. The type of a [`Value`](struct.Value.html) is dynamic in that it generally isn't known at compile time but once created a `Value` can't change its type. [`TypedValue`](struct.TypedValue.html) has a statically known type and dereferences to `Value` so it can be used everywhere `Value` references are accepted. Supported types are `bool`, `i8`, `u8`, `i32`, `u32`, `i64`, `u64`, `f32`, `f64`, `String` and objects (`T: IsA`). # Examples ``` use glib::prelude::*; // or `use gtk::prelude::*;` use glib::{TypedValue, Value}; // Value and TypedValue implement From<&i32>, From<&str> // and From>. Another option is the `ToValue` trait. let mut num = 10.to_value(); let mut hello = Value::from("Hello!"); let none: Option<&str> = None; let str_none = Value::from(none.clone()); let typed_str_none = TypedValue::from(none); // `is` tests the type of the value. assert!(num.is::()); assert!(hello.is::()); // `get` tries to get a value of specific type and returns None // if the type doesn't match or the value is None. assert_eq!(num.get(), Some(10)); assert_eq!(num.get::(), None); assert_eq!(hello.get(), Some(String::from("Hello!"))); assert_eq!(hello.get::(), Some(String::from("Hello!"))); assert_eq!(str_none.get::(), None); // `typed` tries to convert a `Value` to `TypedValue`. let mut typed_num = num.downcast::().unwrap(); let mut typed_hello = hello.downcast::().unwrap(); // `str_none` is not an `i32` assert!(str_none.downcast::().is_err()); // `get` assert!(typed_hello.get().unwrap() == "Hello!"); assert!(typed_str_none.get() == None); // Numeric types can't have value `None`, `get` always returns `Some`. // Such types have `get_some`, which avoids unnecessary `unwrap`ping. assert_eq!(typed_num.get().unwrap(), 10); assert_eq!(typed_num.get_some(), 10); // `set_none` sets the value to `None` if the type supports it. typed_hello.set_none(); assert!(typed_hello.get().is_none()); // `set` takes an optional reference for types that support `None`. typed_hello.set(Some("Hello again!")); assert!(typed_hello.get().unwrap() == "Hello again!"); // `set_some` is the only setter for types that don't support `None`. typed_num.set_some(&20); assert_eq!(typed_num.get_some(), 20); ``` A generic value capable of carrying various types. Once created the type of the value can't be changed. Some types (e.g. `String` and objects) support `None` values while others (e.g. numeric types) don't. See the [module documentation](index.html) for more details. Tries to downcast to a `TypedValue`. Returns `Ok(TypedValue)` if the value carries a type corresponding to `T` and `Err(self)` otherwise. Tries to get a value of type `T`. Returns `Some` if the type is correct and the value is not `None`. This function doesn't distinguish between type mismatches and correctly typed `None` values. Use `downcast` or `is` for that. Returns `true` if the type of the value corresponds to `T`. Returns the type of the value. Returns whether `Value`s of type `src` can be transformed to type `dst`. A statically typed [`Value`](struct.Value.html). It dereferences to `Value` and can be used everywhere `Value` references are accepted. See the [module documentation](index.html) for more details. Returns the value. Types that don't support a `None` value always return `Some`. See `get_some`. Returns the value. This method is only available for types that don't support a `None` value. Sets the value. This method is only available for types that support a `None` value. Sets the value to `None`. This method is only available for types that support a `None` value. Sets the value. Converts to `Value`. Returns a `Value` clone of `self`. Returns the type identifer of `self`. This is the type of the value to be returned by `to_value`. Extracts a value. Types that don't support a `None` value always return `Some`. Extracts a value. Only implemented for types that don't support a `None` value. Sets a value. Only implemented for types that support a `None` value. Sets a value. `Variant` binding and helper traits. [`Variant`](struct.Variant.html) is an immutable dynamically-typed generic container. Its type and value are defined at construction and never change. `Variant` types are described by [`VariantType`](../struct.VariantType.html) "type strings". Although `GVariant` supports arbitrarily complex types, this binding is currently limited to the basic ones: `bool`, `u8`, `i16`, `u16`, `i32`, `u32`, `i64`, `u64`, `f64` and `&str`/`String`. # Examples ``` use glib::prelude::*; // or `use gtk::prelude::*;` use glib::Variant; // Using the `ToVariant` trait. let num = 10.to_variant(); // `is` tests the type of the value. assert!(num.is::()); // `get` tries to extract the value. assert_eq!(num.get::(), Some(10)); assert_eq!(num.get::(), None); // `Variant` implements `From` let hello = Variant::from("Hello!"); // `get_str` tries to borrow a string slice. assert_eq!(hello.get_str(), Some("Hello!")); assert_eq!(num.get_str(), None); ``` A generic immutable value capable of carrying various types. See the [module documentation](index.html) for more details. Returns the type of the value. Returns `true` if the type of the value corresponds to `T`. Tries to extract a value of type `T`. Returns `Some` if `T` matches the variant's type. Tries to extract a `&str`. Returns `Some` if the variant has a string type (`s`, `o` or `g` type strings). Converts to `Variant`. Returns a `Variant` clone of `self`. Extracts a value. Tries to extract a value. Returns `Some` if the variant's type matches `Self`. Returns `VariantType` of `Self`. Returns the `VariantType` corresponding to `Self`. Describes `Variant` types. The `Variant` type system (based on the D-Bus one) describes types with "type strings". `VariantType` is an owned immutable type string (you can think of it as a `Box` statically guaranteed to be a valid type string), `&VariantTy` is a borrowed one (like `&str`). Tries to create a `VariantType` from a string slice. Returns `Ok` if the string is a valid type string, `Err` otherwise. Describes `Variant` types. This is a borrowed counterpart of [`VariantType`](struct.VariantType.html). Essentially it's a `str` statically guaranteed to be a valid type string. Tries to create a `&VariantTy` from a string slice. Returns `Ok` if the string is a valid type string, `Err` otherwise. Converts a type string into `&VariantTy` without any checks. Creates `&VariantTy` with a wildcard lifetime from a `GVariantType` pointer. Returns a `GVariantType` pointer. Converts to a string slice. `IMPL` The `glib_wrapper!` macro and miscellaneous wrapper traits. Defines a wrapper type and implements the appropriate traits. The basic syntax is ```ignore glib_wrapper! { Documentation pub struct $name($kind<$foreign>); match fn { $fn_name => /* a closure-like expression , ... } } ``` This creates a wrapper named `$name` around the foreign type `$foreign` of `$kind` (one of `Boxed`, `Shared`, `Object`) using expressions from the `match fn` block to implement type-specific low-level operations (the expression will be evaluated in `unsafe` context). ### Boxed Boxed records with single ownership. ```ignore glib_wrapper! { Text buffer iterator pub struct TextIter(Boxed); match fn { copy => |ptr| ffi::gtk_text_iter_copy(ptr), free => |ptr| ffi::gtk_text_iter_free(ptr), } } ``` `copy`: `|*const $foreign| -> *mut $foreign` creates a copy of the value. `free`: `|*mut $foreign|` frees the value. `get_type`: `||` (optional) returns the `Type`, if any ### Shared Records with reference counted shared ownership. ```ignore glib_wrapper! { Object holding timing information for a single frame. pub struct FrameTimings(Shared); match fn { ref => |ptr| ffi::gdk_frame_timings_ref(ptr), unref => |ptr| ffi::gdk_frame_timings_unref(ptr), } } ``` `ref`: `|*mut $foreign|` increases the refcount. `unref`: `|*mut $foreign|` decreases the refcount. `get_type`: `||` (optional) returns the `Type`, if any ### Object Objects -- classes and interfaces. ```ignore glib_wrapper! { Object representing an input device. pub struct Device(Object); match fn { get_type => || ffi::gdk_device_get_type(), } } ``` ```ignore glib_wrapper! { A container with just one child. pub struct Bin(Object): Container, Widget, Buildable; match fn { get_type => || ffi::gtk_bin_get_type(), } } ``` Implementing types from other crates requires specifying their FFI counterparts as well: ```ignore glib_wrapper! { pub struct Application(Object): [ gio::Application => gio_ffi::GApplication, gio::ActionGroup => gio_ffi::GActionGroup, gio::ActionMap => gio_ffi::GActionMap, ]; match fn { get_type => || ffi::gtk_application_get_type(), } } ``` `get_type: || -> GType` returns the type identifier of the class or interface. A wrapper struct. Foreign type represented by the struct. gtk-rs-lgpl-docs-0.1.12/glib/vendor.md010064400007650000024000005533161350370316500156570ustar0000000000000000 Contains the public fields of a GByteArray. Adds the given bytes to the end of the `ByteArray`. The array will grow in size automatically if necessary. ## `array` a `ByteArray` ## `data` the byte data to be added ## `len` the number of bytes to add # Returns the `ByteArray` Frees the memory allocated by the `ByteArray`. If `free_segment` is `true` it frees the actual byte data. If the reference count of `array` is greater than one, the `ByteArray` wrapper is preserved but the size of `array` will be set to zero. ## `array` a `ByteArray` ## `free_segment` if `true` the actual byte data is freed as well # Returns the element data if `free_segment` is `false`, otherwise `None`. The element data should be freed using `g_free`. Transfers the data from the `ByteArray` into a new immutable `Bytes`. The `ByteArray` is freed unless the reference count of `array` is greater than one, the `ByteArray` wrapper is preserved but the size of `array` will be set to zero. This is identical to using `Bytes::new_take` and `ByteArray::free` together. ## `array` a `ByteArray` # Returns a new immutable `Bytes` representing same byte data that was in the array Creates a new `ByteArray` with a reference count of 1. # Returns the new `ByteArray` Create byte array containing the data. The data will be owned by the array and will be freed with `g_free`, i.e. it could be allocated using `g_strdup`. ## `data` byte data for the array ## `len` length of `data` # Returns a new `ByteArray` Adds the given data to the start of the `ByteArray`. The array will grow in size automatically if necessary. ## `array` a `ByteArray` ## `data` the byte data to be added ## `len` the number of bytes to add # Returns the `ByteArray` Atomically increments the reference count of `array` by one. This function is thread-safe and may be called from any thread. ## `array` A `ByteArray` # Returns The passed in `ByteArray` Removes the byte at the given index from a `ByteArray`. The following bytes are moved down one place. ## `array` a `ByteArray` ## `index_` the index of the byte to remove # Returns the `ByteArray` Removes the byte at the given index from a `ByteArray`. The last element in the array is used to fill in the space, so this function does not preserve the order of the `ByteArray`. But it is faster than `ByteArray::remove_index`. ## `array` a `ByteArray` ## `index_` the index of the byte to remove # Returns the `ByteArray` Removes the given number of bytes starting at the given index from a `ByteArray`. The following elements are moved to close the gap. ## `array` a `ByteArray` ## `index_` the index of the first byte to remove ## `length` the number of bytes to remove # Returns the `ByteArray` Sets the size of the `ByteArray`, expanding it if necessary. ## `array` a `ByteArray` ## `length` the new size of the `ByteArray` # Returns the `ByteArray` Creates a new `ByteArray` with `reserved_size` bytes preallocated. This avoids frequent reallocation, if you are going to add many bytes to the array. Note however that the size of the array is still 0. ## `reserved_size` number of bytes preallocated # Returns the new `ByteArray` Sorts a byte array, using `compare_func` which should be a `qsort`-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg). If two array elements compare equal, their order in the sorted array is undefined. If you want equal elements to keep their order (i.e. you want a stable sort) you can write a comparison function that, if two elements would otherwise compare equal, compares them by their addresses. ## `array` a `ByteArray` ## `compare_func` comparison function Like `ByteArray::sort`, but the comparison function takes an extra user data argument. ## `array` a `ByteArray` ## `compare_func` comparison function ## `user_data` data to pass to `compare_func` Atomically decrements the reference count of `array` by one. If the reference count drops to 0, all memory allocated by the array is released. This function is thread-safe and may be called from any thread. ## `array` A `ByteArray` A simple refcounted data type representing an immutable sequence of zero or more bytes from an unspecified origin. The purpose of a `Bytes` is to keep the memory region that it holds alive for as long as anyone holds a reference to the bytes. When the last reference count is dropped, the memory is released. Multiple unrelated callers can use byte data in the `Bytes` without coordinating their activities, resting assured that the byte data will not change or move while they hold a reference. A `Bytes` can come from many different origins that may have different procedures for freeing the memory region. Examples are memory from `g_malloc`, from memory slices, from a `MappedFile` or memory from other allocators. `Bytes` work well as keys in `HashTable`. Use `Bytes::equal` and `Bytes::hash` as parameters to `HashTable::new` or `HashTable::new_full`. `Bytes` can also be used as keys in a `Tree` by passing the `Bytes::compare` function to `Tree::new`. The data pointed to by this bytes must not be modified. For a mutable array of bytes see `ByteArray`. Use `Bytes::unref_to_array` to create a mutable array for a `Bytes` sequence. To create an immutable `Bytes` from a mutable `ByteArray`, use the `ByteArray::free_to_bytes` function. Creates a new `Bytes` from `data`. `data` is copied. If `size` is 0, `data` may be `None`. ## `data` the data to be used for the bytes ## `size` the size of `data` # Returns a new `Bytes` Creates a new `Bytes` from static data. `data` must be static (ie: never modified or freed). It may be `None` if `size` is 0. ## `data` the data to be used for the bytes ## `size` the size of `data` # Returns a new `Bytes` Creates a new `Bytes` from `data`. After this call, `data` belongs to the bytes and may no longer be modified by the caller. `g_free` will be called on `data` when the bytes is no longer in use. Because of this `data` must have been created by a call to `g_malloc`, `g_malloc0` or `g_realloc` or by one of the many functions that wrap these calls (such as `g_new`, `g_strdup`, etc). For creating `Bytes` with memory from other allocators, see `Bytes::new_with_free_func`. `data` may be `None` if `size` is 0. ## `data` the data to be used for the bytes ## `size` the size of `data` # Returns a new `Bytes` Creates a `Bytes` from `data`. When the last reference is dropped, `free_func` will be called with the `user_data` argument. `data` must not be modified after this call is made until `free_func` has been called to indicate that the bytes is no longer in use. `data` may be `None` if `size` is 0. ## `data` the data to be used for the bytes ## `size` the size of `data` ## `free_func` the function to call to release the data ## `user_data` data to pass to `free_func` # Returns a new `Bytes` Compares the two `Bytes` values. This function can be used to sort GBytes instances in lexicographical order. If `self` and `bytes2` have different length but the shorter one is a prefix of the longer one then the shorter one is considered to be less than the longer one. Otherwise the first byte where both differ is used for comparison. If `self` has a smaller value at that position it is considered less, otherwise greater than `bytes2`. ## `bytes2` a pointer to a `Bytes` to compare with `self` # Returns a negative value if `self` is less than `bytes2`, a positive value if `self` is greater than `bytes2`, and zero if `self` is equal to `bytes2` Compares the two `Bytes` values being pointed to and returns `true` if they are equal. This function can be passed to `HashTable::new` as the `key_equal_func` parameter, when using non-`None` `Bytes` pointers as keys in a `HashTable`. ## `bytes2` a pointer to a `Bytes` to compare with `self` # Returns `true` if the two keys match. Get the byte data in the `Bytes`. This data should not be modified. This function will always return the same pointer for a given `Bytes`. `None` may be returned if `size` is 0. This is not guaranteed, as the `Bytes` may represent an empty string with `data` non-`None` and `size` as 0. `None` will not be returned if `size` is non-zero. ## `size` location to return size of byte data # Returns a pointer to the byte data, or `None` Get the size of the byte data in the `Bytes`. This function will always return the same value for a given `Bytes`. # Returns the size Creates an integer hash code for the byte data in the `Bytes`. This function can be passed to `HashTable::new` as the `key_hash_func` parameter, when using non-`None` `Bytes` pointers as keys in a `HashTable`. # Returns a hash value corresponding to the key. Creates a `Bytes` which is a subsection of another `Bytes`. The `offset` + `length` may not be longer than the size of `self`. A reference to `self` will be held by the newly created `Bytes` until the byte data is no longer needed. Since 2.56, if `offset` is 0 and `length` matches the size of `self`, then `self` will be returned with the reference count incremented by 1. If `self` is a slice of another `Bytes`, then the resulting `Bytes` will reference the same `Bytes` instead of `self`. This allows consumers to simplify the usage of `Bytes` when asynchronously writing to streams. ## `offset` offset which subsection starts at ## `length` length of subsection # Returns a new `Bytes` Increase the reference count on `self`. # Returns the `Bytes` Releases a reference on `self`. This may result in the bytes being freed. If `self` is `None`, it will return immediately. Unreferences the bytes, and returns a new mutable `ByteArray` containing the same byte data. As an optimization, the byte data is transferred to the array without copying if this was the last reference to bytes and bytes was created with `Bytes::new`, `Bytes::new_take` or `ByteArray::free_to_bytes`. In all other cases the data is copied. # Returns a new mutable `ByteArray` containing the same byte data Unreferences the bytes, and returns a pointer the same byte data contents. As an optimization, the byte data is returned without copying if this was the last reference to bytes and bytes was created with `Bytes::new`, `Bytes::new_take` or `ByteArray::free_to_bytes`. In all other cases the data is copied. ## `size` location to place the length of the returned data # Returns a pointer to the same byte data, which should be freed with `g_free` An opaque structure representing a checksumming operation. To create a new GChecksum, use `Checksum::new`. To free a GChecksum, use `Checksum::free`. Creates a new `Checksum`, using the checksum algorithm `checksum_type`. If the `checksum_type` is not known, `None` is returned. A `Checksum` can be used to compute the checksum, or digest, of an arbitrary binary blob, using different hashing algorithms. A `Checksum` works by feeding a binary blob through `Checksum::update` until there is data to be checked; the digest can then be extracted using `Checksum::get_string`, which will return the checksum as a hexadecimal string; or `Checksum::get_digest`, which will return a vector of raw bytes. Once either `Checksum::get_string` or `Checksum::get_digest` have been called on a `Checksum`, the checksum will be closed and it won't be possible to call `Checksum::update` on it anymore. ## `checksum_type` the desired type of checksum # Returns the newly created `Checksum`, or `None`. Use `Checksum::free` to free the memory allocated by it. Copies a `Checksum`. If `self` has been closed, by calling `Checksum::get_string` or `Checksum::get_digest`, the copied checksum will be closed as well. # Returns the copy of the passed `Checksum`. Use `Checksum::free` when finished using it. Frees the memory allocated for `self`. Gets the digest from `self` as a raw binary vector and places it into `buffer`. The size of the digest depends on the type of checksum. Once this function has been called, the `Checksum` is closed and can no longer be updated with `Checksum::update`. ## `buffer` output buffer ## `digest_len` an inout parameter. The caller initializes it to the size of `buffer`. After the call it contains the length of the digest. Gets the digest as an hexadecimal string. Once this function has been called the `Checksum` can no longer be updated with `Checksum::update`. The hexadecimal characters will be lower case. # Returns the hexadecimal representation of the checksum. The returned string is owned by the checksum and should not be modified or freed. Resets the state of the `self` back to its initial state. Feeds `data` into an existing `Checksum`. The checksum must still be open, that is `Checksum::get_string` or `Checksum::get_digest` must not have been called on `self`. ## `data` buffer used to compute the checksum ## `length` size of the buffer, or -1 if it is a null-terminated string. Gets the length in bytes of digests of type `checksum_type` ## `checksum_type` a `ChecksumType` # Returns the checksum length, or -1 if `checksum_type` is not supported. The hashing algorithm to be used by `Checksum` when performing the digest of some data. Note that the `ChecksumType` enumeration may be extended at a later date to include new hashing algorithm types. Use the MD5 hashing algorithm Use the SHA-1 hashing algorithm Use the SHA-256 hashing algorithm Use the SHA-512 hashing algorithm (Since: 2.36) Use the SHA-384 hashing algorithm (Since: 2.51) Enumeration representing a month; values are `DateMonth::January`, `DateMonth::February`, etc. `DateMonth::BadMonth` is the invalid value. invalid value January February March April May June July August September October November December `GDateTime` is an opaque structure whose members cannot be accessed directly. Creates a new `DateTime` corresponding to the given date and time in the time zone `tz`. The `year` must be between 1 and 9999, `month` between 1 and 12 and `day` between 1 and 28, 29, 30 or 31 depending on the month and the year. `hour` must be between 0 and 23 and `minute` must be between 0 and 59. `seconds` must be at least 0.0 and must be strictly less than 60.0. It will be rounded down to the nearest microsecond. If the given time is not representable in the given time zone (for example, 02:30 on March 14th 2010 in Toronto, due to daylight savings time) then the time will be rounded up to the nearest existing time (in this case, 03:00). If this matters to you then you should verify the return value for containing the same as the numbers you gave. In the case that the given time is ambiguous in the given time zone (for example, 01:30 on November 7th 2010 in Toronto, due to daylight savings time) then the time falling within standard (ie: non-daylight) time is taken. It not considered a programmer error for the values to this function to be out of range, but in the case that they are, the function will return `None`. You should release the return value by calling `DateTime::unref` when you are done with it. ## `tz` a `TimeZone` ## `year` the year component of the date ## `month` the month component of the date ## `day` the day component of the date ## `hour` the hour component of the date ## `minute` the minute component of the date ## `seconds` the number of seconds past the minute # Returns a new `DateTime`, or `None` Creates a `DateTime` corresponding to the given [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601) `text`. ISO 8601 strings of the form `````